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Foreword 


This manual describes several utility programs that aid the 
programmer and system designer in the software development process. 
Collectively, these utilities allow you to assemble 8080 assembly 
language modules, link them together to form an executable program, 
and generate a cross-reference listing of the variables used in a 
program. With these utilities, you can also create and manage your 
own libraries of object modules, as well as create large programs by 
breaking them into separate overlays. 

The Programmer's Utilities Guide assumes you are familiar with 
the CP/M® or MP/M II™ Operating System environment. It also 
assumes you are familiar with the basic elements of assembly 
language programming as described in the 8080 Assembly Language 
Programming Manual, published by Intel. 

MAC™ , the CP/M macro assembler, translates 8080 assembly 
language statements and produces a hex format object file suitable 
for processing in the CP/M environment. MAC is upward compatible 
with the standard CP/M nonmacro assembler, ASM™. (See the CP/M 
documentation published by Digital Research.) 

MAC facilities include assembly of Intel® 8080 microcomputer 
mnemonics, along with assembly-t ime expressions, conditional 
assembly, page formatting features, and a powerful macro processor 
compatible with the standard Intel definition. MAC also accepts 
most programs prepared for the Processor Technology Software #1 
assembler, requiring only minor modifications. This revision is 
not compatible with previous versions. 

MAC is supplied on a standard disk, along with a number of 
library files. MAC requires about 12K of machine code and table 
space, along with an additional 2.5K of I/O buffer space. Because 
the BDOS portion of CP/M is coresident with MAC, the minimum usable 
memory size for MAC is about 20K. Any additional memory adds to the 
available Symbol Table area, allowing larger programs to be 
assembled. 

Sections 1 through 5 describe the simple assembler facilities 
of MAC: 8080 mnemonic forms, expressions, and conditional assembly. 
These facilities are similar to those of the CP/M assembler (ASM). 
If you are familiar with ASM, you might want to skip Sections 1 
through 5 and begin with Section 6. 

Sections 6 through 8 describe MAC macro facilities in detail. 
Section 7 describes inline macros, and Section 8 explains the 
definition and evaluation of stored macros. If you are familiar 
with macros, briefly skim these sections, referring primarily to the 
examples. Section 9 explains macro applications, common macro 
forms, and programming practices. Skim the examples and refer back 
to the explanations for a detailed discussion of each program. 
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Sections 10 through 13 describe other features of macro 
assembler operation. Section 10 details assembly parameters. 
Section 11 introduces iterative improvement, a common debugging 
practice used in developing macros and macro libraries. Section 12 
defines MAC'S symbol storage requirements. 

Section 13 explains the differences between MAC and RMAC™* the 
CP/M Relocating Macro Assembler. 

Section 14 details XREF, an assembly language cross-reference 
program used with MAC and RMAC. 

Section 16 describes LINK-80™ , the linkage editor that 
combines relocatable object modules into an absolute file ready to 
run under CP/M or MP/M II. Section 17 describes how to use LINK-80, 
in conjunction with the PL/I-80™ compiler, to produce overlays. 
Section 18 explains how to use LIB-80™, the software librarian for 
creating and manipulating library files containing object modules. 

The appendixes contain a complete list of error messages output 
by each of the utility programs. 
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Section 1 

Macro Assembler Operation Under CP/M 


Start MAC with a command of the form: 

MAC filename 

where filename corresponds to the assembly language file with an 
assumed filetype ASM. During the translation process, MAC creates a 
file called filename.HEX containing the machine code in the Intel 
hexadecimal format. You can subsequently load or test this HEX 
file. (See the LOAD command and the Dynamic Debugging Tool, DDT TM , 
in the CP/M documentation.) MAC also creates a file named 
filename.PRN containing an annotated source listing, along with a 
file called filename.SYM containing a sorted list of symbols defined 
in the program. 

Listing 1-1 provides an example of MAC output for a sample 
assembly language program stored on the disk under the name 
SAMPLE.ASM. Type MAC SAMPLE followed by a carriage return to 
execute the macro assembler. The PRN, SYM, and HEX files then 
appear as shown in the listing. The assembler listing file (PRN) 
includes a 16-column annotation at the left showing the values of 
literals, machine code addresses, and generated machine code. Note 
that an equal sign (=) is used to denote literal values to avoid 
confusion with machine code addresses. (See Section 4.3.) Output 
files contain tab characters (ASCII CTRL-I) whenever possible to 
conserve disk space. 


Source Program (SAMPLE.ASM) 


bdos 

wchar 


org 

lOOh 


;transient program area 

equ 

0005h 


;bdos entry point 

equ 

2 


;write character function 

enter 

with ccp' 

1 s 

return address in the stack 

write 

a single 

character (?) and return 

mvi 

c,wchar 

;write character function 

mvi 

e, '?' 


?character to write 

call 

bdos 


ywrite the character 

ret 

end 

lOOh 


;return to the ccp 
;start address is lOOh 


Listing 1-1. Sample ASM, PRN, SYM, and HEX files from MAC 
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Assembler Listing File (SAMPLE.PRN) 


0100 


ORG 

100H 

,-TRANSIENT PROGRAM AREA 

0005 

= 

BDOS 

EQU 

0005H ;BDOS ENTRY POINT 

0002 

= 

WCHAR 

EQU 

2 ?WRITE CHARACTER FUNCTION 



7 

ENTER 

WITH CCP'S RETURN ADDRESS IN THE STACK 



; 

WRITE 

A SINGLE CHARACTER (?) AND RETURN 

0100 

0E02 


MVI 

C,WCHAR ;WRITE CHARACTER FUNCTION 

0102 

1E3F 


MVI 

E,'?' ;CHARACTER TO WRITE 

0104 

CD0500 


CALL 

BDOS ;WRITE THE CHARACTER 

0107 

C9 


RET 

?RETURN TO THE CCP 

0108 



END 

100H ;START ADDRESS IS 100H 


Assembler Sorted Symbol File (SAMPLE.SYM) 

0005 BDOS 0002 WCHAR 

Assembler Hex Output File (SAMPLE.HEX) 

:080100000E021E3FCD0500C9EF 
:00010000FF 


Listing 1-1. (continued) 


End of Section 1 
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Section 2 
Program Format 


A program acceptable as input to the macro assembler consists 
of a sequence of statements of the form 

line# label operation operand comment 

where any or all of the elements can be present in a particular 
statement. Each assembly language statement terminates with a 
carriage return and line-feed. Note that the ED program 
automatically inserts the line-feed when you enter a carriage 
return. You can also terminate an assembly language statement by 
typing the exclamation point (1) character. MAC treats this 
character as an end-of-line. You can write multiple assembly 
language statements on the same physical line if you separate them 
with exclamation points. 

A sequence of one or more blank or tab characters delimits 
statement elements. Tab characters are preferred because they 
conserve source file space and reduce the listing file size. The 
tab characters are not expanded until the file is printed or typed 
at the console. 

The line# is an optional decimal integer value representing the 
source program line number. It is allowed on any source line. The 
assembler ignores the optional line#. 

The label field takes the form: 

identifier 

or 

identifier: 

The label field is optional, except where noted in particular 
statement types. 

The identifier is a sequence of alphanumeric characters: 
alphabetics, question marks, commercial at-signs, and numbers, the 
first character of which is not numeric. You can use identifiers 
freely to label elements such as program steps and assembler 
directives, but identifiers cannot exceed 16 characters in length. 

All characters are significant in an identifier, except for the 
embedded dollar sign ($) that you can use to improve name 
readability. Further, MAC treats all lower-case alphabetics in an 
identifier as though they were upper-case. Note that the colon (:) 
following the identifier in a label is optional. The following 
examples are all valid labels: 
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2 Program Format 


x xy 

x? xyls 

xlx2 @123: 

Gamma @GAMMA 

x234$5678$9012$3456: 


long$name 
longer$named$data 
??@@abcDEF 
?ARE$WE$HERE? 


The operation field contains an assembler directive (pseudo 
operation), 8080 machine operation code, or a macro invocation with 
optional parameters. The pseudo operations and machine operation 
codes are described in Section 5. Macro calls are discussed in 
Section 6. 

The operand field of the statement contains an expression 
formed from constant and label operands, with arithmetic, logical, 
and relational operations on these operands. Properly formed 
expressions are detailed in Section 3. 

A leading semicolon character denotes the comment field, which 
contains arbitrary characters until the next carriage return or 
exclamation point character. MAC reads, lists, and otherwise 
ignores comment fields. To maintain compatibility with other 
assemblers, MAC also treats statements that begin with an asterisk 
(*) in column one as comment lines. 

The assembly language program is thus a sequence of statements 
of the form described above, terminated optionally by an END 
statement. The assembler ignores all statements following the END. 


End of Section 2 
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Section 3 

Forming the Operand 


Expressions in the operand field consist of simple operands— 
labels, constants, and reserved words—combined into properly formed 
subexpressions by arithmetic and logical operators. MAC carries out 
expression computation as the assembly proceeds. Each expression 
produces a 16-bit value during the assembly. The number of 
significant digits in the result must not exceed the intended use. 
That is, if an expression is to be used in a byte move immediate 
(see the MVI instruction), the absolute value of the operand must 
fit within an 8-bit field. Instructions for each expression give 
the restrictions on expression significance. 


3.1 Labels 

A label is an identifier of a statement. The label's value is 
determined by the type of statement it precedes. If the label 
occurs on a statement that generates machine code or reserves memory 
space, such as a MOV instruction or a DS pseudo operation, then the 
label is given the value of the program address it labels. If the 
label precedes an EQU or SET, then the label is given the value that 
results from evaluating the operand field. In a macro definition, 
the label is given a text value, a sequence of ASCII characters, 
that is the body of the macro definition. With the exception of the 
SET and MACRO pseudo operations, an identifier can label only one 
statement. 

When a nonmacro label appears in the operand field, the 
assembler substitutes its 16-bit value. This value can then be 
combined with other operands and operators to form the operand field 
for an instruction. When a macro identifier appears in the 
operation field of the statement, the text stored as the value of 
the macro name is substituted for the name. In this case, the 
operand field of the statement contains actual parameters. These 
are substituted for dummy parameters in the body of the macro 
definition. Later sections give the exact mechanisms for defining, 
calling, and substituting macro text. 


3.2 Numeric Constants 

A numeric constant is a 16-bit value in a number base. A 
trailing radix indicator denotes the base, called the radix of the 
constant. The radix indicators are 


B binary constant (base 2) 

0 octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 
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3.2 Numeric Constants 


Q is an alternate radix indicator for octal numbers because the 
letter 0 is easily confused with the digit 0. Any numeric constant 
that does not terminate with a radix indicator is assumed to be a 
decimal constant. 

A constant is composed of a sequence of digits, followed by an 
optional radix indicator, where the digits are in the appropriate 
range for the radix. Binary constants must be composed of 0 and 1 
digits. Octal constants can contain digits in the range 0-7. 
Decimal constants contain decimal digits. Hexadecimal constants 
contain decimal digits and hexadecimal digits A through F, 
corresponding to the decimal numbers 10 through 15. 

Note that the leading digit of a hexadecimal constant must be a 
decimal digit to avoid confusing a hexadecimal constant with an 
identifier. A leading 0 prevents ambiguity. A constant composed in 
this manner produces a binary number that can be contained within a 
16-bit counter, truncated on the right by the assembler. Like 
identifiers, embedded $ symbols are allowed within constants to 
improve readability. 

Finally, the radix indicator translates to upper-case if a 
lower-case letter is encountered. The following examples are valid 
numeric constants: 


1234 1234D 1100B 1111$0000$1111$0000B 

1234H OFFFEH 33770 33$77$22Q 

3377o Ofe3h 1234d Offffh 


3.3 Reserved Words 

Several reserved character sequences have predefined meanings 
in the operand field of a statement. The names of 8080 registers 
and their values are given in Table 3-1. 


Table 3-1. 8080 Registers and Values 


symbol 

value 

symbol 

value 

A 

7 

B 

0 

C 

1 

D 

2 

E 

3 

H 

4 

L 

5 

M 

6 

SP 

6 

PSW 

6 


Lower-case names have the same values as their upper-case 
equivalents. Machine instructions can also be used in the operand 
field, resulting in their internal codes. For instructions that 
require operands, where the operand is a part of the binary bit 
pattern of the instruction (e.g., MOV A,B) , the value of the 
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3.3 Reserved Words 


instruction is the bit pattern of the instruction, with zeros in the 
optional fields. For example, the statement 

LXI H,MOV 

assembles an LXI H instruction with an operand equal to 40H, the 
value of the MOV instruction with zeros as operands. 

When the $ symbol appears in the operand field—not embedded 
within identifiers and numbers—its value is the address of the 
beginning of the current instruction. For example, the two 
statements 

X: JMP X 


and 


JMP $ 

produce a jump instruction to the current location. As an 
exception, the $ symbol at the beginning of a logical line can 
introduce assembly formatting instructions. (See Section 10.) 


3.4 String Constants 

String constants represent sequences of graphic ASCII 
characters, enclosed in apostrophes ('). All strings must be fully 
contained within the current physical line, with the exclamation 
point (!) character within strings treated as an ordinary string 
character. Each individual string must not exceed 64 characters in 
length, or MAC reports an error. The apostrophe character can be 
included in a string by typing two apostrophes (*'). The assembler 
reads the two apostrophes as a single apostrophe. 

Note that particular operation codes can require the string 
length to be no longer than one or two characters. The LXI 
instruction, for example, accepts a character string operand of one 
or two characters. The CPI instruction accepts only a one-character 
string. The DB instruction, however, allows strings zero through 64 
characters long in its list of operands. In the case of single¬ 
character strings, the value is the 8-bit ASCII code for the 
character, without case translation. Two-character strings produce 
a 16-bit value with the second character as the low-order byte and 
the first character as the high-order byte. For example, the string 
constant 'A' is equivalent to 41H. The two-character string 'AB' 
produces the 16-bit value 4142H. The following are valid strings in 
MAC statements: 


'A' 'AB' 'ab* 'c' ,,,, 'she said "hello"' 

Note: You can use the ampersand (&) character to cause evaluation 
of dummy arguments within macro expansions inside string quotes. 
Section 8 details the substitution process. 
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3.5 Operators 


3.5 Arithmetic, Logical, and Relational Operators 

MAC can combine the operands described above in algebraic 
notation using properly formed operands, operators, and 
parenthesized expressions. The operators MAC recognizes in the 
operand field are listed below. 


• a+b produces the arithmetic sum of a and b; +b is b. 

• a-b produces the arithmetic difference between a and b; -b is 
0-b. 

• a*b is the unsigned multiplication of a by b. 

• a/b is the unsigned division of a by b. 

• a MOD b is the remainder after division of a by b. 

• a SHL b produces a shifted left by b, with zero right fill. 

• a SHR b produces a shifted right by b, with zero left fill. 

• NOT b is the bit-by-bit logical inverse of b. 

• a EQ b produces true if a equals b, false otherwise. 

• a LT b produces true if a is less than b, false otherwise. 

• a LE b produces true if a is less than or equal to b, false 
otherwise. 

• a GT b produces true if a is greater than b, false otherwise. 

• a GE b produces true if a is greater than or equal to b, false 
otherwise. 

• a AND b produces the bitwise logical AND of a and b. 

• a OR b produces the bitwise logical OR of a and b. 

• a XOR b produces the logical exclusive OR of a and b. 

• HIGH b is identical to b SHR 8 (high-order byte of b). 

• LOW b is identical to b AND OFFH (low-order byte of b). 


The letters a and b represent operands that are treated as 16-bit 
unsigned quantities in the range 0-65535. All arithmetic operators 
produce a 16-bit unsigned arithmetic result. Relational operators 
produce a true (OFFFFH) or false (0000H) 16-bit result. Logical 
operators operate bit-by-bit on their operands producing a 16-bit 
result of 16 individual bit operations. The HIGH and LOW functions 
always produce a 16-bit result with a high-order byte of zero. 
Table 3-2 lists arithmetic, logical, and relational operators. 
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3.5 Operators 


Table 3-2. Operators 


arithmetic 

relational 

logical 

+ 

EQ 

NOT 

- 

LT 

AND 

* 

LE 

OR 

/ 

GT 

XOR 

MOD 

GE 


SHL 

NE 


SHR 




MAC performs all computations during the assembly process as 
16-bit unsigned operations, as described above. The resulting 
expression must fit the operation code in which it is used. For 
example, the expression used in an ADI (add immediate) instruction 
must fit into an 8-bit field. Thus, the high-order byte must be 
zero. If the computed value does not fit the field, the assembler 
produces a value error for that statement. 

As an exception to this rule, negative 8-bit values are allowed 
in 8-bit fields under the following conditions: if the program 
attempts to fill an 8-bit field with a 16-bit value that has all Is 
in the high-order byte, and the sign bit is set, then the high order 
byte is truncated, and no error is reported. This condition arises 
when a negative sign is placed in front of a constant. For example, 
the value -2 is defined and computed as 0-2, producing the 16-bit 
value OFFFEH, where the high-order byte (OFFH) contains extended 
sign bits that are all Is, and the low-order byte (OFEH) has the 
sign bit set. The following instructions do not produce value 
errors in MAC: 

ADI -1 ADI -15 ADI -127 ADI -128 ADI 0FF80H 
The following instructions produce value errors: 

ADI 256 ADI 32768 ADI -129 ADI 0FF7FH 

The special operator NUL is used in conjunction with macro 
definition and expansion operations. The NUL operator takes a 
single operand. NUL must be the last operator in the operand field. 

Expressions can be formed from simple operands such as labels, 
numeric constants, string constants, and machine operation codes, or 
from fully enclosed parenthesized expressions such as 
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3.5 


Operators 


10 + 20 , 

10H+37Q, 

Ll/3, 

(L2 + 4) SHR 3, 

('a' and 5fh) + 'O', 

('BB' + B) OR (PSW + M), 
(1+ (2+C)) shr (A- (B +1)), 
(HIGH A) SHR 3 


where blanks and tabs are ignored between the operators and operands 
of the expression. 


3.6 Precedence of Operators 

MAC assumes operators have a relative precedence of application 
allowing expressions to be written without nested parentheses. The 
resulting expression has assumed parentheses that are defined by 
this relative precedence. The order of application of operators in 
unparenthesized expressions is listed below. Operators listed first 
have highest precedence. These are applied first in an 
unparenthesized expression. Operators listed last have lowest 
precedence and are applied last. Operators listed on the same line 
have equal precedence and are applied from left to right as they are 
encountered in an expressions 


* / MOD SHL SHR 
+ - 

EQ LT LE GT GE NE 
NOT 
AND 

OR XOR 
HIGH LOW 


The following expressions are equivalents 


a * b + c produces (a * b) + c 
a + b * c produces a + (b * c) 

a MOD b * c SHL d produces ((a MOD b) * c) SHL D 
a OR b AND NOT c + d SHL e produces 
a OR (b AND (NOT (c + (d SHL e)))) 


Balanced parenthesized subexpressions can always override the 
assumed parentheses. The last expression above can be rewritten to 
force application of operators in a different order, as shown belows 

(a OR b) AND (NOT c) + d SHL e 

resulting in the assumed parentheses 

(a OR b) AND ((NOT c) + (d SHL e)) 
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3.6 Precedence of Operators 


Note that an unparenthesized expression is well formed only if the 
expression that results from inserting the assumed parentheses is 
well formed. 

Relational operators can be expressed in either of two forms, 
as shown in Table 3-3. 


Table 3-3. Equivalent Forms 
of Relational Operators 


< 

LT 

< = 

LE 

= 

EQ 

<> 

NE 

>= 

GE 

> 

GT 


End of Section 3 
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Section 4 

Assembler Directives 


Assembler directives set labels to specific values during 
assembly, perform conditional assembly, define storage areas, and 
specify starting addresses in the program. Each assembler directive 
is denoted by a pseudo operation that appears in the operation field 
of the statement. Table 4-1 lists the acceptable pseudo operations. 


Table 4-1. Pseudo Operations 


Directive 

Meaning 

ORG 

sets the program or data origin. 

END 

terminates the physical program. 

EQU 

performs a numeric equate. 

SET 

performs a numeric set or assignment. 

IF 

begins a conditional assembly. 

ELSE 

is an alternate to a previous IF. 

END IF 

marks the end of conditional assembly . 

DB 

defines data bytes or strings of data. 

DW 

defines words of storage (double bytes). 

DS 

reserves uninitialized storage areas. 

PAGE 

defines the listing page size for output. 

TITLE 

enables page titles and options. 


In addition to those listed above, several pseudo operations are 
used in conjunction with the macro processing facilities. MACRO, 
EXITM, ENDM, REPT, IRPC, IRP, LOCAL, and MACLIB are reserved words. 
They are fully described in Sections 7 and 8. The nonmacro pseudo 
operations are detailed below. 


4.1 The ORG Directive 

The ORG statement takes the form 
label ORG expression 

where label is an optional program label—an identifier followed by 
an optional colon (s)—and expression is a 16-bit expression 
consisting of operands defined before the ORG statement. The 
assembler begins machine code generation at the location specified 
in the expression. There can be any number of ORG statements within 
a program. There are no checks to ensure that you are not 
redefining overlapping memory areas. Note that most programs 
written for CP/M begin with an ORG 100H statement that causes 
machine code generation to begin at the base of the CP/M Transient 
Program Area. Programs assembled with RMAC and linked with LINK-80 
do not need an ORG 100H statement. (See Section 13 and 15.) 
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4.1 The ORG Directive 


If the ORG statement has a label, then the label takes on the 
value given by the expression. The expression is the next machine 
code address to assemble. This label can then be used in the 
operand field of other statements to represent this expression. 


4.2 The END Directive 

The END statement is optional in an assembly language program? 
if present, it must be the last statement. All statements following 
the END are ignored. The two forms of the END statement are: 

label END 

label END expression 

where the label is optional. If the first form is used, the 
assembly process stops, and the default starting address of the 
program is taken as 0000. Otherwise, the expression is evaluated 
and becomes the program starting address. This starting address is 
included in the last record of the Intel format machine code hex 
file resulting from the assembly. Most CP/M assembly language 
programs end with the statement 

END 100H 

resulting in the default starting address of 100H, the beginning of 
the Transient Program Area. 


4.3 The EQU Directive 

The EQU (equate) statement names synonyms for particular 
numeric values. The directive takes the form: 

label EQU expression 

The label must be present, and it must not label any other 
statement. The assembler evaluates the expression and assigns this 
value to the identifier given in the label field. The identifier is 
usually a name describing the value in a more human-oriented manner. 
You can use this name throughout the program as a parameter for 
certain functions. Suppose, for example, that data received from a 
teletype appears on an input port, and data is sent to the teletype 
through the next output port in sequence. The series of equate 
statements that can define these ports for a particular hardware 
environment is shown below. 


TTYBASE 

EQU 

10H 

;BASE 

1 TTY 

PORT 

TTYIN 

EQU 

TTYBASE 

; TTY 

DATA 

IN 

TTYOUT 

EQU 

TTYBASE+1 

; TTY 

DATA 

OUT 
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4.3 The EQU Directive 


At a later point in the program, the statements that access the 
teletype could appear as 

IN TTYIN ;READ TTY DATA TO A 

OUT TTYOUT ;WRITE DATA FROM A 

making the program more readable than the absolute I/O port 
addresses. If the hardware environment is later redefined to start 
the teletype communications ports at 7FH instead of 10H, the first 
statement need only be changed to 

TTYBASE EQU 7FH ;BASE PORT NUMBER FOR TTY 

and the program can be reassembled without changing any other 
statements. 


4.4 The SET Directive 

The SET statement is similar to the EQU, taking the form 
label SET expression 

except that the label, taken as a variable name, can occur on other 
SET statements within the program. The expression is evaluated and 
becomes the current value associated with the label. Thus, unlike 
the EQU statement, where a label takes on a single value throughout 
the program, the SET statement can assign different values to a name 
at different parts of the program. In particular, the SET statement 
gives the label a value that is valid from the current SET statement 
to the point where the label occurs on the next SET statement. The 
use of SET is similar to the EQU, except that SET is used more often 
to control conditional assembly within macros. 


4.5 The IF, ELSE, and ENDIF Directives 

The IF, ELSE, and ENDIF directives define a range of assembly 
language statements to be included or excluded during the assembly 
process. The IF and ENDIF statements alone can bound a group of 
statements to be conditionally assembled, as shown in the following 
example: 


IF expression 

statement#l 

statement#2 

statement#n 

ENDIF 


Upon encountering the IF statement, the assembler evaluates the 
expression following the IF. All operands in the expression must be 
defined ahead of the IF statement. If the expression evaluates to a 
nonzero value, then statement#l through statement#n are assembled. 
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4.5 IF, ELSE, and ENDIF 


If the expression evaluates to zero, then the statements are listed 
but not assembled. 

Conditional assembly is often used to write a single generic 
program that includes a number of possible alternative subroutines 
or program segments, where only a few of the possible alternatives 
are to be included in any given assembly. Listings 4-1 and 4-2 give 
an example of such a program. 

Assume that a console device, either a teletype or a CRT, is 
connected to an 8080 microcomputer through I/O ports. Due to the 
electronic environment, the current loop teletype is connected 
through ports 10H and 11H, while the RS-232 CRT is connected through 
ports 20H and 21H. The program continually loops, reading and 
writing console characters. The program shown below operates either 
with a teletype or a CRT, depending on the value of the symbol TTY. 

Listing 4-1 shows an assembly for the teletype environment. 
Listing 4-2 shows the assembly for a CRT-based system. Note that 
the assembler leaves the leftmost 16 columns blank when statements 
are skipped due to a false condition. 


CP/M MACRO ASSEM 2.0 

#001 

Teletype Echo Program 

FFFF 

= 

TRUE 

EQU 

0FFFFH ;DEFINE TRUE 

0000 

= 

FALSE 

EQU 

NOT TRUE?DEFINE FALSE 

FFFF 

= 

TTY 

EQU 

TRUE ? SET TTY ON 

0010 

= 

TTYBASE 

EQU 

10H ?BASE OF TTY PORTS 

0020 

= 

CRTBASE 

EQU 

2OH ;BASE OF CRT PORTS 




IF 

TTY ?ASSEMBLE TTY PORTS 




TITLE 

'Teletype Echo Program' 

0010 

= 

CONIN 

EQU 

TTYBASE ?CONSOLE INPUT 

0011 

= 

CONOUT 

EQU 

ENDIF 

TTYBASE+1 ?CONSOLE OUT 




IF 

NOT TTY ?ASSEMBLE CRT PORTS 




TITLE 

'CRT Echo Program* 



CONIN 

EQU 

CRTBASE ?CONSOLE IN 



CONOUT 

EQU 

CRTBASE+1 ?CONSOLE OUT 




ENDIF 


0000 

DB10 

ECHO: 

IN 

CONIN ?READ CONSOLE 





CHARACTER 

0002 

D311 


OUT 

CONOUT ?WRITE CONSOLE 





CHARACTER 

0004 

C30000 


JMP 

ECHO 

0007 



END 



Listing 4-1. Conditional Assembly with TTY True 
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4.5 IF, ELSE, and ENDIF 


CP/M MACRO ASSEM 

2.0 

#001 

CRT Echo 

Program 


FFFF 

= 

TRUE 

EQU 

0FFFFH 

?DEFINE TRUE 


0000 

= 

FALSE 

EQU 

NOT TRUE 

;DEFINE FALSE 


0000 

= 

TTY 

EQU 

FALSE 

? SET CRT ON 


0010 

= 

TTYBASE 

EQU 

10H 

?BASE OF TTY ] 

PORTS 

0020 

= 

CRTBASE 

EQU 

20H 

?BASE OF CRT ] 

PORTS 




IF 

TTY 

?ASSEMBLE TTY 

PORTS 




TITLE 

'Teletype 

Echo Program' 




CON IN 

EQU 

TTYBASE 

;CONSOLE 

INPUT 



CONOUT 

EQU 

TTYBASE+1 

?CONSOLE 

OUT 




ENDIF 







IF 

NOT TTY 

;ASSEMBLE CRT 

PORTS 




TITLE 

'CRT Echo 

Program' 


0020 

= 

CON IN 

EQU 

CRTBASE 

;CONSOLE 

IN 

0021 

= 

CONOUT 

EQU 

CRTBASE+1 

;CONSOLE 

OUT 




ENDIF 




0000 

DB20 

ECHO: 

IN 

CONIN 

?READ CONSOLE 







CHARACTER 


0002 

D321 


OUT 

CONOUT 

?WRITE CONSOLE 






CHARACTER 


0004 

C30000 


JMP 

ECHO 



0007 



END 





Listing 4-2. Conditional Assembly with TTY False 


The ELSE statement can be used as an alternative to an IF 
statement. The ELSE statement must occur between the IF and ENDIF 
statements. The form is 


IF expression 

statement#l 

statement#2 

statement#n 

ELSE 

statement#n+l 

statement#n+2 

statement#m 

ENDIF 


If the expression produces a nonzero (true) value, then statements 1 
through n are assembled as before. However, the assembly process 
skips statements n+1 through m. When the expression produces a zero 
value (false), MAC skips statements 1 through n and assembles 
statements n+1 through m. For example, the conditional assembly 
shown in Listings 4-1 and 4-2 can be rewritten as shown in Listing 
4-3. 
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CP/M MACRO ASSEM 

2.0 

#001 

FFFF 

s 

TRUE 

EQU 

0000 

= 

FALSE 

EQU 

0000 

= 

TTY 

EQU 

0010 

= 

TTYBASE 

EQU 

0020 


CRTBASE 

EQU 

IF 

TITLE 



CONIN 

EQU 



CONOUT 

EQU 

ELSE 

TITLE 

0020 

= 

CONIN 

EQU 

0021 

= 

CONOUT 

EQU 




ENDIF 

0000 

DB20 

ECHO: 

IN 

0002 

D321 


OUT 

0004 

C30000 


JMP 

0007 



END 


4.5 IF, ELSE, and ENDIF 


CRT Echo Program 

OFFFFH ;DEFINE TRUE 

NOT TRUE;DEFINE FALSE 
FALSE ;SET CRT ON 

10H ;BASE OF TTY PORTS 

2OH ;BASE OF CRT PORTS 

TTY ;ASSEMBLE TTY PORTS 

’Teletype ,Ectio Program' 

TTYBASE ;CONSOLE INPUT 

TTYBASE+1 ;CONSOLE OUT 

;ASSEMBLE CRT PORTS 
'CRT Echo Program' 

CRTBASE ;CONSOLE IN 

CRTBASE+1 ;CONSOLE OUT 


CONIN ;READ CONSOLE CHARACTER 
CONOUT ?WRITE CONSOLE CHARACTER 
ECHO 


Listing 4-3. Conditional Assembly Using ELSE for Alternate 


Properly balanced IF, ELSE, and ENDIF statements can be 
completely contained within the boundaries of outer encompassing 
conditional assembly groups. The structure outlined below shows 
properly nested IF, ELSE, and ENDIF statements: 


IF exp#l 

groupil 

IF exp#2 

group#2 

ELSE 

group#3 

ENDIF 

group# 4 

ELSE 

group#5 

IF exp#3 

group#6 

ENDIF 

group#7 

ENDIF 


Groups 1 through 7 are sequences of statements to be conditionally 
assembled, and exp#l through exp#3 are expressions that control the 
conditional assembly. If exp#l is true, then group#1 and group#4 
are always assembled, and groups 5, 6, and 7 are skipped. Further, 
if exp#l and exp#2 are both true, then group#2 is also included in 
the assembly. Otherwise, group#3 is included. If exp#l produces a 
false value, groups 1, 2, 3, and 4 are skipped, and groups 5 and 7 
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4.5 IF, ELSE, and ENDIF 


are always assembled. If exp#3 is true under these circumstances, 
then group#6 is also included with 5 and 7. Otherwise, it is 
skipped in the assembly. A structure similar to this is shown in 
Listing 4-4, where literal true/false values show conditional 
assembly selection. 


There can be up to eight pending IFs or ELSEs with unresolved 
ENDIFs at any point in the assembly, but the assembly usually 
becomes unreadable after two or three levels or nesting. The 
nesting level restriction also holds, however, for pending IFs and 
ELSEs during macro evaluation. Nesting level overflow produces an 
error during assembly. 


FFFF 

= 

TRUE 

EQU 

0FFFFH 

0000 

= 

FALSE 

EQU 

NOT TRUE 




IF 

FALSE 




MVI 

A,1 




IF 

TRUE 




MVI 

A,2 




ELSE 

MVI 

A,3 




ENDIF 

MVI 

ELSE 

A,4 

0000 

3E05 


MVI 

A,5 




IF 

TRUE 

0002 

3E06 


MVI 

A,6 




ELSE 

MVI 

ENDIF 

A,7 

0004 

3E08 


MVI 

ENDIF 

END 

A,8 


?DEFINE TRUE 
?DEFINE FALSE 


Listing 4-4. Sample Program Using Nested IF, ELSE, and ENDIF 


4.6 The DB Directive 

The DB directive defines initialized storage areas in single¬ 
precision (byte) format. 

The statement form is 

label DB e#l, e#2, . . . , e#n 

where the label is optional, and e#l through e#n are either 
expressions that produce 8-bit values (the high-order eight bits are 
zeros, or the high-order nine bits are ones), or are ASCII strings 
no longer than 64 characters each. There is no practical 
restriction on the number of expressions included on a single source 
line. The assembler evaluates expressions and places them into the 
machine code sequentially following the last program address 
generated. 
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4.6 The DB Directive 


String characters are similarly placed into memory, starting 
with the first character and ending with the last character. 
Strings longer than two characters cannot be used as operands in 
more complicated expressions. They must stand alone between the 
commas. Note that ASCII characters are always placed in memory with 
the high-order (parity) bit reset to zero. Further, recall that 
there is no translation from lower to upper-case within strings. 
The optional label can be used to reference the data area throughout 
the program. The following are examples of valid DB statements: 


data: 

DB 

0,1,2,3,4,5,6 


DB 

data and 0ffh,5,377Q,l+2+3+4 

signon: 

DB 

'please type your name:',cr,If,0 
'AB' SHR 8, 'C', 'DE' AND 7FH 


DB 


DB 

HIGH data, LOW (signon GT data) 


4.7 The DW Directive 

The DW statement is similar to the DB statement except double¬ 
precision (two-byte) words of storage are initialized. The form of 
the DW statement is 

label DW e#l, e#2,. . . , e#n 

where the label is optional, and e#l through e#n are expressions 
that produce 16-bit values. Note that ASCII strings one or two 
characters long are allowed, but strings longer that two characters 
are disallowed. In all cases, the data storage is consistent with 
the 8080 processor; the least significant byte of the expression is 
stored first in memory, followed by the most significant byte. The 
following are examples of properly formed DW statements: 

doub: DW Offefh, doub+4, signon-$,255+255 

DW 'a', 5, 'AB', 'CD', doub LT signon 


4.8 The DS Directive 

The DS statement reserves an area of uninitialized memory and 
takes the form 

label DS expression 

where the label is optional. The assembler begins subsequent .code 
generation after the area reserved by the DS. Thus, the DS 
statement given above has exactly the same effect as the statement 
sequences: 

label: EQU $ ;CURRENT CODE LOC 

ORG $+expression ?MOVE PAST AREA 
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4.8 The DS Directive 


4.9 The PAGE and TITLE Directives 

The PAGE and TITLE pseudo operations give you control over the 
output formatting that is sent to the PRN file or directly to the 
printer device. The forms for the PAGE statement are 

PAGE 

PAGE expression 

If the PAGE statement stands alone, an ASCII CTRL-L (form-feed) is 
sent to the output file after the PAGE statement has been printed. 
The PAGE command is often issued directly ahead of major sections of 
an assembly language program, such as a group of subroutines, to 
cause the next statement to appear at the top of the following page. 

The second form of the PAGE command specifies the output page 
size. In this case, the expression following the PAGE pseudo 
operation determines the number of output lines to be printed on 
each page. If the expression is zero, there are no page breaks. 
The print file is simply a continuous sequence of annotated output 
lines. If the expression is nonzero, then the page size is set to 
the value of the expression. Form-feeds are issued to cause page 
ejects when this count is reached for each page. The assembler 
initially assumes that 

PAGE 56 

is in effect, producing a page eject at the beginning of the listing 
and at each 56-line increment. 

The TITLE directive takes the form 

TITLE string-constant 

where the string-constant is an ASCII string enclosed in 
apostrophes, not exceeding 64 characters in length. If a TITLE 
pseudo operation is given during the assembly, each page of the 
listing file is prefixed with the title line, preceded by a standard 
MAC header. The title line thus appears as 

CP/M MACRO ASSEM n.n #ppp string-constant 

where n.n is the MAC version number, #ppp is the page number in the 
listing, and string-constant is the string given in the TITLE pseudo 
operation. MAC initially assumes that the TITLE operation is not in 
effect. When specified, the title line and the blank line following 
the title are not included in the line count for the page. No more 
than one TITLE statement is included in a program. Similarly, only 
one PAGE statement with the expression option is included. 

If a TITLE statement is included, and the Symbol Table is being 
appended to the PRN file (see Section 10), then the SYM file also 
contains the title at the beginning of the symbol listing with page 
breaks given by either the default or specified value of the PAGE 
statement. 
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4.10 A Sample Program 


4.10 A Sample Program Using Pseudo Operations 

The program in Listing 4-5 demonstrates the pseudo operations 
available in MAC. The sample program, called TYPER, operates in the 
CP/M environment by selecting one of three messages for output at 
the console. This program is created using the ED program, 
assembled using MAC, and then placed into COM file format using the 
CP/M LOAD function. After these steps have been accomplished, TYPER 
executes at the Console Command Processor level of CP/M by typing 
one of the commands: 

TYPER A 
TYPER B 
TYPER C 

to select message A, B, or C for printing. The TYPER program loads 
under the CCP and jumps to the label START where the 8080 stack is 
initialized. The TYPER program then prints its sign-on message: 

'typer' version 1.0 

The program then retrieves the first character typed at the 
console following the command TYPER. This character should be A, B, 
or C. If one of these letters is not specified, then TYPER reboots 
the CP/M system to give control back to the CCP. If a valid letter 
is provided, TYPER selects one of the three messages (MESS0A, 
MESS@B, or MESS0C) and prints it at the console before returning to 
CP/M. 


The TITLE and PAGE statements produce a title at the beginning 
of each page; page size is 33 lines, excluding the title lines. 
Form-feeds are suppressed. A number of EQU statements at the 
beginning improve program readability. Note that throughout the 
program the exclamation point allows several simple assembly 
language statements on the same line. Although multiple statements 
make the program more compact, they often decrease the overall 
readability of the source program. Note also that the program 
terminates without the END statement. The END statement is 
necessary only if a starting address is specified. The END 
statement is often included, however, to maintain compatibility with 
other assemblers. 

The DB statements labeled by SIGNON contain simple strings of 
characters and expressions that produce single-byte values. The DW 
statement following TABLE defines the base address of each string, 
corresponding to A, B, and C. Finally, the DS statement at the. end 
of the program reserves space for the stack defined within the TYPER 
program. 
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4.10 A Sample Program 


CP/M MACRO ASSEM 2.0 

TITLE 
PAGE 
PRINT 


#001 


Typer Program 


000A 

= 

VERS 

EQU 

10 

0000 

= 

BOOT 

EQU 

0000H 

0005 

= 

BDOS 

EQU 

0005H 

005C 

= 

TFCB 

EQU 

005CH 

0002 

= 

WCHAR 

EQU 

2 

000D 

= 

CR 

EQU 

0DH 

000A 

= 

LF 

EQU 

0AH 

0010 

= 

STKSIZ 

EQU 

16 

0100 


i 

ORG 

100H 

0100 

C31201 


JMP 

START 


'Typer Program' 

33 

GE SELECTED BY THE INPUT COMMAND A,B, OR C 
;VERSION NUMBER N.N 
;REBOOT ENTRY POINT 
;BDOS ENTRY POINT 

;DEFAULT FILE CONTROL BLOCK (GET A,B, OR C) 
;WRITE CHARACTER FUNCTION 
;CARRIAGE RETURN CHARACTER 
;LINE FEED CHARACTER 

;SIZE OF LOCAL STACK (IN DOUBLE BYTES) 

;ORIGIN AT BASE OF TPA 
;JUMP PAST THE MESSAGE SUBROUTINE 


WMESSAGE: 


0103 7EB7C8 
0106 5F0E02E5 
010A CD0500E1 
010E 23C30301 


;WRITE THE STRING AT THE ADDRESS GIVEN BY HL 'TIL 00 

MOV A,Ml ORA A! RZ ;RETURN IF AT 00 

MOV E, A1 MVI C,WCHAR! PUSH H ;READY TO PRINT 

CALL BDOS1 POP H ;CHARACTER PRINTED, GET NEXT 

INX H! JMP WMESSAGE 



START: 

;ENTER 

HERE FROM 

THE CCP, RESET TO LOCAL STACK 

0112 31C101 


LXI 

SP,STACK 

;SET TO LOCAL STACK 

0115 213701 


LXI 

H, SIGNON 

?WRITE THE MESSAGE 

0118 CD0301 


CALL 

WMESSAGE 

?'TYPER' VERSION N.N 

011B 3A5D00 


LDA 

TFCB+1 

;GET FIRST CHAR TYPED AFTER NAME 

011E D641 


SUI 

'A' 

;NORMALIZE TO 0,1,2 

0120 FE03 


CPI 

TABLEN 

;COMPARE WITH THE TABLE LENGTH 

0122 D20000 


JNC 

BOOT 

;REBOOT IF NOT VALID 


COMPUTE INDEX INTO ADDRESS TABLE BASED ON A'S VALUE 


Listing 4-5. TYPER Prograa Listing 
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4.10 A Sample Program 



CP/M MACRO ASSEM 2.0 

#002 Typer 

Program 

0125 

5F 

MOV 

E,A 

;LOW ORDER INDEX 

0126 

1600 

MVI 

D, 0 

?EXTENDED TO DOUBLE PRECISION 

0128 

214D01 

LXI 

H,TABLE 

;BASE OF THE TABLE TO INDEX 

012B 

19 

DAD 

D 

;SINGLE PRECISION INDEX 

012C 

19 

DAD 

D 

;DOUBLE PRECISION INDEX 

012D 

5E 

MOV 

E ,M 

;LOW ORDER BYTE TO E 

012E 

23 

INX 

H 


012F 

56 

MOV 

D,M 

;HIGH ORDER MESSAGE ADDRESS TO DE 

0130 

EB 

XCHG 


;READY FOR PRINTOUT 

0131 

CD0301 

CALL 

WMESSAGE 

;MESSAGE WRITTEN TO CONSOLE 

0134 

C30000 

JMP 

BOOT 

;REBOOT, GO BACK TO CCP LEVEL 


J 

; 

DATA 

AREAS 



SIGNON: 




0137 

2774797065 

DB 

'''typer'' version ' 

0147 

312E30 

DB 

VERS/10+'0', 

'.', VERS MOD 10 +'0' 

014A 

0D0A00 

DB 

CR,LF,0 ;END 

OF MESSAGE 


TABLE: ;OF MESSAGE BASE ADDRESSES 

0140 5301670182 DW MESS@A,MESS@B,MESS@C 

0003 = TABLEN EQU ($-TABLE)/2 ;LENGTH OF TABLE 


; 

0153 7468697320MESS@A: DB 'this is message a',CR,LF,0 

0167 796F752073MESS@B: DB 'you selected b this time',CR,LF,0 

0182 7468697320MESS@C: DB 'this message comes out for c',CR r LF,0 


01A1 

DS STKSIZ*2 

STACK: 

;RESERVES AREA FOR STACK 


Listing 4-5. 

(continued) 


End of Section 4 


End of Section 4 


All Information Presented Here 


is Proprietary to Digital Research 


24 




Section 5 
Operation Codes 


Operation codes, found in the operation field of the statement, 
form the principal components of assembly language programs. MAC 
accepts all the standard mnemonics for the Intel 8080 microcomputer. 
These standard mnemonics are detailed in the 8080 Assembly Language 
Programming Manual , published by Intel. Labels are optional on each 
input line and, if included, take the value of the instruction 
address immediately before the instruction is issued by the 
assembler. The individual operators are listed briefly in the 
following sections. See the Intel documentation for exact operator 
details. In this section, operation codes are categorized for 
discussion; a sample assembly shows the hexadecimal codes produced 
for each operation. The following notation is used throughout: 


e3 represents a 3-bit value in the range 0-7 that 
usually takes one of the predefined register values 
A, B, C, D, H, L, M, SP, or PSW 

e8 represents an 8-bit value in the range 0-255? signed 
8-bit values are also allowed in the range -128 
through +127) 

el6 represents a 16-bit value in the range 0-65535 


where e3, e8, and el6 can be formed from an arbitrary combination of 
operands and operators in a well-formed expression. In some cases, 
the operands are restricted to particular values within the range, 
such as the PUSH instruction. 


5.1 Jumps, Calls, and Returns 


In some cases, the condition flags are tested to determine 
whether or not to take the jump, call, or return. The forms are 
shown below. The jump instructions are 


JMP el6 

JNZ el6 

JZ el6 

JNC el6 

JC el6 

JPO el6 

JPE el6 

JP el6 

JM el6 

. instructions are 

CALL el6 

CNZ el6 

CZ el6 

CNC el6 

CC el6 

CPO el6 

CPE el6 

CP el6 

CM el6 
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5.1 Jumps, Calls, and Returns 


The return instructions are 


RET 

RNC 

RPE 


RNZ 

RC 

RP 


RZ 

RPO 

RM 


The restart instruction takes the form 


RST e3 


and performs exactly the same function as the instruction CALL e3*8 
except that RST e3 requires only one byte of memory. 

Listing 5-1 shows the hexadecimal codes for each instruction, 
along with a short comment on each line describing the function of 
the instruction. 
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CP/M 

MACRO ASSEM 2.0 

#001 

8080 JUMPS, CALLS, AND RETURNS 




TITLE 

'8080 

JUMPS, CALLS, AND RETURNS' 



7 

7 

JUMPS 

ALL REQUIRE A 16-BIT OPERAND 

0000 

C31B00 


JMP 

LI 

;JUMP UNCONDITIONALLY TO LABEL 

0003 

C25C00 


JNZ 

Ll+'A' 

?JUMP ON NON ZERO TO LABEL 

0006 

CA0001 


JZ 

100H 

;JUMP ON ZERO CONDITION TO LABEL 

0009 

D21F00 


JNC 

Ll+4 

;JUMP ON NO CARRY TO LABEL 

oooc 

DA4142 


JC 

'AB' 

;JUMP ON CARRY TO LABEL 

000F 

E21700 


JPO 

$+8 

;JUMP ON PARITY ODD TO LABEL 

0012 

EA0D00 


JPE 

Ll/2 

?JUMP ON EVEN PARITY TO LABEL 

0015 

F24100 


JP 

GAMMA 

;JUMP ON POSITIVE RESULT TO LABEL 

0018 

FA1B00 

Lis 

JM 

LOW LI 

?JUMP ON MINUS TO LABEL 



7 

7 

CALL OPERATIONS ALL REQUIRE A 16-BIT OPERAND 

001B 

CD3600 


CALL 

SI 

;CALL SUBROUTINE UNCONDITIONALLY 

001E 

C43800 


CNZ 

Sl+X 

;CALL SUBROUTINE IF NON ZERO FLAG 

0021 

CC0001 


CZ 

100H 

;CALL SUBROUTINE IF ZERO FLAG 

0024 

D43A00 


CNC 

Sl+4 

;CALL SUBROUTINE IF NO CARRY FLAG 

0027 

DC0000 


CC 

SI MOD 

3;CALL SUBROUTINE IF CARRY FLAG 

002A 

E43200 


CPO 

$ + 8 

?CALL SUBROUTINE IF PARITY ODD 

002D 

EC0900 


CPE 

Sl-$ 

7CALL SUBROUTINE IF PARITY EVEN 

0030 

F44100 


CP 

GAMMA 

?CALL SUBROUTINE IF POSITIVE 

0033 

FC4100 

SI: 

CM 

GAM$MA 

?CALL SUBROUTINE IF MINUS FLAG 



7 

7 

PROGRAMMED RESTART (RST) REQUIRES 3-BIT OPERAND 



7 

(RST X 

IS EQUIVALENT TO CALL X*8) 

0036 

Cl 


RST 

0 

7RESTART TO LOCATION 0 

0037 

DF 


RST 

X+l 




7 

7 

RETURN 

INSTRUCTIONS HAVE NO OPERAND 

0038 

C9 


RET 


7RETURN FROM SUBROUTINE 

0039 

CO 


RNZ 


7RETURN IF NON ZERO 

003A 

C8 


RZ 


7 RETURN IF ZERO FLAG SET 

003B 

DO 


RNC 


7RETURN IF NO CARRY FLAG 

003C 

D8 


RC 


7 RETURN IF CARRY FLAG SET 

003D 

EO 


RPO 


7RETURN IF PARITY IS ODD 

003E 

E8 


RPE 


7RETURN IF PARITY IS EVEN 

003F 

FO 


RP 


?RETURN IF POSITIVE RESULT 

0040 

F8 


RM 


7RETURN IF MINUS FLAG SET 

0002 

= 

7 

X 

GAMMA: 

EQU 

2 


0041 



END 



Listing 5-1. 

Assembly Showing Jumps, 

Calls, Returns, and Restarts 
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5.2 Immediate Operand Instructions 

Several instructions load single- or double-precision registers 
or single-precision memory locations with constant values. Other 
instructions perform immediate arithmetic or logical operations on 
the accumulator (register A). The move immediate instruction takes 
the form: 

MVI e3,e8 

where e3 is the register to receive the data given by the value e8. 
The expression e3 must produce a value corresponding to one of the 
registers A, B, C, D, E, H, L, or the memory location M, which is 
addressed by the HL register pair. 

The accumulator immediate operations take the form: 

ADI e8 ACI e8 SUI e8 SBI e8 

ANI e8 XRI e8 ORI e8 CPI e8 

where the operation is always performed on the accumulator using the 
immediate data value given by the expression e8. 

The load extended immediate instructions take the form: 

LXI e3,el6 

where e3 designates the register pair to receive the double¬ 
precision value given by el6. The expression e3 must produce a 
value corresponding to one of the double-precision register pairs B, 
D, H, or SP. 

Listing 5-2 shows the accumulator immediate operations in an 
assembly language program and briefly describes each instruction. 


CP/M MACRO ASSEM 2.0 #001 IMMEDIATE OPERAND INSTRUCTIONS 

TITLE 'IMMEDIATE OPERAND INSTRUCTIONS' 

; MVI USES A REGISTER (3-BIT) OPERAND AND 8-BIT DATA 


0000 

06FF 


MVI 

B, 255 

;MOVE IMMEDIATE A,B,C,D,E,H,L,M 



7 

ALL 

REMAINING IMMEDIATE OPERATIONS USE A REGISTER 

0002 

C601 


ADI 

1 

;ADD IMMEDIATE TO A W/O CARRY 

0004 

CEFF 


AC I 

0FFH 

;ADD IMMEDIATE TO A WITH CARRY 

0006 

D613 


SUI 

Ll+3 

;SUBTRACT FROM A W/O BORROW (CARRY) 

0008 

DE10 


SBI 

LOW LI 

?SUBTRACT FROM A WITH BORROW (CARRY) 

000A 

E602 


ANI 

$ AND 7 

?LOGICAL AND WITH IMMEDIATE DATA 

oooc 

EE3C 


XRI 

1111$ 00B 

;LOGICAL XOR WITH IMMEDIATE DATA 

000E 

F6FD 

LI: 

ORI 

-3 

?LOGICAL OR WITH IMMEDIATE DATA 

0010 



END 




Listing 5-2. Assembly Using Immediate Operand Instructions 
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5.3 Increment and Decrement 


5.3 Increment and Decrement Instructions 

The 8080 set includes instructions for incrementing or 
decrementing single- and double-precision registers. The 
instruction forms for single-precision registers are 

INR e3 DCR e3 

where e3 produces a value corresponding to register A f B, C, D, H, 
L, or M. These registers correspond to the byte value at the memory 
location addressed by HL. The double-precision instructions are 

INX e3 DCX e3 

where e3 must be equivalent to one of the double-precision register 
pairs B, D, H, or SP. 

Listing 5-3 shows a sample assembly language program using both 
single- and double-precision increment and decrement operations. 



CP/M MACRO 

ASSEM 2.0 

#001 

INCREMENT AND DECREMENT INSTRUCTIONS 



TITLE 

'INCREMENT AND DECREMENT INSTRUCTIONS' 

0000 

7 

} 

INSTRUCTIONS 

REQUIRE REGISTER (3-BIT) OPERAND 

1C 

INR 

E 

;BYTE INCREMENT A,B,C,D,E,H,L,M 

0001 

3D 

DCR 

A 

;BYTE DECREMENT A,B,C,D f E,H,L,M 

0002 

33 

INX 

SP 

;16-BIT INCREMENT B,D,H,SP 

0003 

0B 

DCX 

B 

?16-BIT DECREMENT B,D,H,SP 

0004 


END 




Listing 5-3. Assembly Containing Increment 
and Decrement Instructions 


5.4 Data Movement Instructions 

A number of 8080 instructions move data from memory to the CPU 
and from the CPU to memory. Data movement instructions also include 
a number of register-to-register move operations. The single¬ 
precision move register instruction takes the form 

MOV e3,e3' 

where the e3 and e3' expressions each produce a single-precision 
register A, B, C, D, E, H, L, or M, where the M register corresponds 
to the memory location addressed by HL. The register named by e3 
always receives the 8-bit value given by the register expression 
e3'. The instruction is often read as move to register e3 from 
register e3' . The instruction MOV B,H would thus be read as move to 
register B from register H. Note that the instruction MOV M,M is 
not allowed. 
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5.4 Data Movement Instructions 


The single-precision load and store extended operations take 
the form 


LDAX e3 STAX e3 

where e3 is a register expression that must produce one of the 
double-precision register pairs B or D. The 8-bit value in register 
A is either loaded from (LDAX) or stored to (STAX) the memory 
location addressed by the specified register pair. 

The load and store direct instructions operate on either the A 
register for single-precision operations, or on the HL register pair 
for double-precision operations. Load and store direct instructions 
take the form 

LHLD el6 SHLD el6 LDA el6 STA el6 

where el6 is an expression that produces the memory address to 
obtain (LHLD, LDA) or store (SHLD, STA) the data value. 

The stack pop and push instructions perform double-precision 
load and store operations, with the 8080 stack as the implied memory 
address. The forms are 

POP e3 PUSH e3 

where e3 must evaluate to one of the double-precision register pairs 
PSW, B, D, or H. 

The input and output instructions are also in this category, 
even though they receive and send their data to the electronic 
environment external to the 8080 processor. The input instruction 
reads data to the A register; the output instruction sends data 
from the A register. In both cases, the data port is given by the 
data value that follows the instruction. The forms are 

IN e8 OUT e8 

A set of instructions transfers double-precision values between 
registers and the stack. These instructions are 

XTHL PCHL SPHL XCHG 

Listing 5-4 lists these instructions in an assembly language program 
and briefly describes them. 
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5.4 Data Movement Instructions 


CP/M MACRO ASSEM 2.0 #001 DATA/MEMORY/REGISTER MOVE OPERATIONS 

TITLE 'DATA/MEMORY/REGISTER MOVE OPERATIONS' 


THE MOV INSTRUCTION REQUIRES TWO REGISTER OPERANDS 
(3-BITS) SELECTED FROM A,B,C,D,E,H, OR M (M,M INVALID 


0000 

78 

MOV 

A,B 

;MOVE DATA TO FIRST REGISTER FROM 





;SECOND 


• 

LOAD/STORE EXTENDED REQUIRE REGISTER PAIR B OR D 

0001 

0A 

LDAX 

B 

;LOAD ACCUM FROM ADDRESS GIVEN BY BC 

0002 

12 

STAX 

D 

;STORE ACCUM TO ADDRESS GIVEN BY DE 


• 

LOAD/STORE DIRECT REQUIRE MEMORY ADDRESS 

0003 

2A1900 

LHLD 

Dl 

;LOAD HL DIRECTLY FROM ADDRESS Dl 

0006 

221300 

SHLD 

Dl+2 

;STORE HL DIRECTLY TO ADDRESS Dl+2 

0009 

3A1900 

LDA 

Ol 

;LOAD THE ACCUMULATOR FROM Dl 

oooc 

326400 

STA 

Dl SHL 2;STORE THE ACCUMULATOR TO Dl SHL 2 



PUSH 

AND POP 

REQUIRE PSW OR REGISTER PAIR FROM B,D,H 

000F 

FI 

POP 

PSW 

;LOAD REGISTER PAIR FROM STACK 

0010 

C5 

PUSH 

B 

;STORE REGISTER PAIR TO THE STACK 


9 

INPUT/OUTPUT 

INSTRUCTIONS REQUIRE 8-BIT PORT NUMBER 

0011 

DB06 

IN 

X+2 

;READ DATA FROM PORT NUMBER TO A 

0013 

D3FE 

OUT 

0FEH 

;WRITE DATA TO THE SPECIFIED PORT 


' 

MISCELLANEOUS 

REGISTER MOVE OPERATIONS 

0015 

S3 

XTHL 


;EXCHANGE TOP OF STACK WITH HL 

0016 

E9 

PCHL 


;PC RECEIVES THE HL VALUE 

0017 

F9 

SPHL 


;SP RECEIVES THE HL VALUE 

0018 

EB 

XCHG 


;EXCHANGE DE AND HL 


1 

END OF INSTRUCTION LIST 

0019 

Dl: 

OS 

2 

;DOUBLE WORD TEMPORARY 

00 IB 


DS 

2 

;ANOTHER TEMPORARY 

0004 

= X 

EQU 

4 

;LITERAL VALUE 

001D 


END 



Listing 5-4. 

Assembly 

Using Various Register/Memory Moves 
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5.5 ALU Operations 


5.5 Arithmetic Logic Unit Operations 

The 8080 set includes instructions that operate between the 
accumulator and single-precision registers, including operations on 
the A register and carry flag. The accumulator/register 
instructions are 

ADD e3 ADC e3 SUB e3 SBB e3 

ANA e3 XRA e3 ORA e3 CMP e3 

where e3 produces a value corresponding to one of the single¬ 
precision registers A, B, C, D, E, H, L, or M, where the M register 
is the memory location addressed by the HL register pair. 

The accumulator/carry operations given below operate upon the A 
register, or carry bit, or both. 

DAA CMA STC CMC 

RLC RRC RAL RAR 

The function of each instruction is listed in the comment line shown 
in Listing 5-5. 
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5.5 ALU Operations 


CP/M MACRO ASSEM 2.0 


#001 


ARITHMETIC LOGIC UNIT OPERATIONS 


TITLE 'ARITHMETIC LOGIC UNIT OPERATIONS' 

ASSUME OPERATION WITH ACCUMULATOR AND REGISTER, 
WHICH MUST PRODUCE A, B, C, D, E, H, L, OR M 


0000 80 


ADD 

0001 8D 


ADC 

0002 94 


SUB 

0003 99 


SBB 

0004 Al 


ANA 

0005 AF 


XRA 

0006 B0 


ORA 

0007 BC 


CMP 


? 

7 

DOUI 

0008 09 


DAD 


7 

7 

REMi 

0009 27 


DAA 

000A 2F 


CMA 

000B 37 


STC 

000C 3F 


CMC 

000D 07 


RLC 

000E OF 


RRC 

000F 17 


RAL 

0010 IF 


RAR 

0011 

7 

END 


B 

L 

H 

B+l 

C 

A 

B 

H 


B 


;ADD REGISTER TO A W/O CARRY 
;ADD TO A WITH CARRY INCLUDED 
?SUBTRACT FROM A W/O BORROW 
;SUBTRACT FROM A WITH BORROW 
;LOGICAL AND WITH REGISTER 
;LOGICAL XOR WITH REGISTER 
;LOGICAL OR WITH REGISTER 
;COMPARE REGISTER, SETS FLAGS 


?DOUBLE ADD B,D,H,SP TO HL 


REMAINING OPERATIONS HAVE NO OPERANDS 

DECIMAL ADJUST REGISTER A USING LAST OP 
COMPLEMENT THE BITS OF THE A REGISTER 
SET THE CARRY FLAG TO 1 
COMPLEMENT THE CARRY FLAG 
8-BIT ACCUM ROTATE LEFT, AFFECTS CY 

8- BIT ACCUM ROTATE RIGHT, AFFECTS CY 

9- BIT CY/ACCUM ROTATE LEFT 
9-BIT CY/ACCUM ROTATE RIGHT 


Listing 5-5. Assembly Showing ALU Operations 
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5.5 ALU Operations 


The double-precision add instruction performs a 16-bit addition 
of a register pair (B, D, H, or SP) into the 16-bit value in the HL 
register pair. This addition produces the 16-bit (unsigned) sum of 
the two values. The sum is placed into the HL register pair. The 
form is 


DAD e3 


5.6 Control Instructions 

The four remaining instructions in the 8080 set are control 
instructions. These take the forms 

HLT 

DI 

El 

NOP 

They stop the processor (HLT), enable the interrupt system (El), 
disable the interrupt system (DI), or perform a no-operation (NOP). 


End of Section 5 
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Section 6 

An Introduction to Macro Facilities 


The fundamental difference between the Digital Research ASM and 
MAC assemblers is that ASM provides only the facilities for 
assembling 8080 operation codes, and MAC includes a powerful macro 
processing facility. MAC implements the industry standard Intel 
macro definition, which includes the following pseudo operations. 

Macro definitions allow groups of instructions to be stored and 
substituted in the source program as the macro names are 
encountered. Definitions and macro calls can be nested; symbols can 
be constructed through concatenation using the special & operator, 
and locally defined symbols can be created using the LOCAL pseudo 
operation. Macro parameters can be formed to pass arbitrary strings 
of text to a specific macro for substitution during expansion. 

The MACLIB (macro library) feature allows the programmer to 
define a set of macros, equates, and sets and automatically includes 
them in a program. A macro library can contain an instruction set 
for another central processor that is not directly supported by the 
MAC built-in mnemonics. The macro library can also include general 
purpose input/output macros used in programs that operate in the 
CP/M environment to perform peripheral or disk I/O functions. 

IRPC, IRP, and REPT pseudo operations repeat source statements 
under control of a count or list of characters or items to be 
substituted each time the assembler rereads the statements. This 
feature is particularly useful in generating groups of assembly 
language statements with similar structure, such as a set of File 
Control Blocks where only the filetype is changed in each statement. 

To illustrate the power of macro facility, consider the macro 
library shown in Listing 6-1, which resides in a disk file called 
MSGLIB.LIB. This macro library contains macro definitions that have 
standard instruction sequences for program startup, message typeout, 
and program termination. The program shown in Listing 6-2 provides 
an example of the use of this macro library. The assembly shown in 
Listing 6-2 lists both the macro calls and the statements in macro 
expansions that generate machine code. The statements marked by + 
in Listing 6-2 are generated from the macro calls. The remaining 
statements are a part of the calling program. 

The macro call 
ENTCCP 10 

in Listing 6-2 shows a specific expansion of ENTCCP (enter from 
CCP) . ENTCCP is defined in Listing 6-1. The macro call causes MAC 
to retrieve the definition—the text between MACRO and ENDM in 
Listing 6-1—and substitute this text following the macro call in 
Listing 6-2. Upon entry to the program from CCP, this macro saves 
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6 Macro Facilities 


the stack pointer (SP) into a variable called @ENTSP for later 
retrieval. The stack pointer is then reset to a local area for the 
remainder of the program execution. 

The size of the local stack is defined by the macro parameter 
named in the macro definition as SSIZE (see Listing 6-1), and filled 
in at the call with the value 10. The ENTCCP macro reserves space 
for a local stack of SSIZE=10 double bytes (2*10 bytes) and, after 
setting up the stack, branches around this reserved area to continue 
the program execution. 
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Macro Facilities 


SIMPLE MACRO LIBRARY FOR MESSAGE TYPEOUT 


REBOOT 

EQU 

0000H 

?WARM START ENTRY POINT 


TPA 

EQU 

0100H 

TRANSIENT PROGRAM AREA 


BDOS 

EQU 

0005H 

SYSTEM ENTRY POINT 


TYPE 

EQU 

2 

WRITE CONSOLE CHARACTER FUNCTION 


CR 

EQU 

ODH 

CARRIAGE RETURN 


LF 

EQU 

OAH 

LINE FEED 


;MACRO 

DEFINITIONS 



CHROUT 

MACRO 


WRITE A CONSOLE CHARACTER FROM REGISTER 

A 


MVI 

C,TYPE 

..type FUNCTION 



CALL 

ENDM 

BDOS 

?ENTER THE BDOS TO WRITE THE CHARACTER 


TYPEOUT 

MACRO 7MESSAGE ;TYPE LITERAL MESSAGE AT 

CONSOLE 


LOCAL 

PASTSUB 

;JUMP PAST SUBROUTINE INITIALLY 



JMP 

PASTSUB 



MSGOUT: 


;?THIS SUBROUTINE PRINTS THE MESSAGE STARTING AT 

HL 'TIL 


MOV 

E, M 

;NEXT CHARACTER TO E 



MOV 

A,E 

;TO ACCUM TO TEST FOR 00 



ORA 

A 

; =00? 



RZ 


?RETURN IF END OF MESSAGE 



INX 

H 

;OTHERWISE MOVE TO NEXT CHARACTER AND PRINT 


PUSH 

CHROUT 

H 

?SAVE MESSAGE ADDRESS 



POP 

H j 

;7 RECALL MESSAGE ADDRESS 



JMP 

MSGOUT j 

! 7FOR ANOTHER CHARACTER 


PASTSUB: 




i 

7 ? 

REDEFINE THE TYPEOUT MACRO AFTER THE FIRST INVOCATION 


TYPEOUT 

MACRO ??MESSAGE 



LOCAL 

TYMSG j 

! 7 LABEL THE LOCAL MESSAGE 



LOCAL 

PASTM 




LXI 

H,TYMSG ; 

\?ADDRESS THE LITERAL MESSAGE 



CALL 

MSGOUT j 

17CALL THE PREVIOUSLY DEFINED SUBROUTINE 



JMP 

PASTM 



} ? 

INCLUDE 

THE LITERAL MESSAGE AT THIS POINT 


TYMSG: 

DB 

'FROM CONSOLE: &??MESSAGE' f CR f LF,0 


? ? 

ARRIVE 

HERE TO CONTINUE THE MAINLINE CODE 


PASTM: 

ENDM 





TYPEOUT <?MESSAGE> 
ENDM 


Listing 6-1. A Sample Macro Library 
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ENTCCP 

MACRO 

SSIZE ;ENTER PROGRAM FROM CCP, 


LOCAL 

START ;;AROUND THE STACK 


LXI 

H, 0 


DAD 

SP ;? SP VALUE IN HL 


SHLD 

0ENTSP ;;ENTRY SP 


LXI 

SP,@STACK 7 ? SET TO LOCAL STACK 


JMP 

START 


IF 

NUL SSIZE 


DS 

ELSE 

32 77 DEFAULT 16 LEVEL STACK 


DS 

ENDIF 

2*SSIZE 

0STACK 

: 

77 LOW END OF STACK 

@ENTSP 

s 

DS 2 7 7 ENTRY SP 

START: 

ENDM 


RETCCP 

MACRO 

7RETURN TO CONSOLE PROCESSOR 


LHLD 

SPHL 

0ENTSP ?7 RELOAD CCP STACK 


RET 

77BACK TO THE CCP 


ENDM 


ABORT 

MACRO 

7ABORT THE PROGRAM 


JMP 

REBOOT 


ENDM 

END OF MACRO LIBRARY 


RESERVE 2*SSIZE STACK LOCS 


Listing 6-1. (continued) 
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CP/M MACRO ASSEM 2.0 


#001 SAMPLE MESSAGE OUTPUT MACRO 


TITLE 'SAMPLE MESSAGE OUTPUT MACRO' 


0100 


0100+210000 

0103+39 

0104+222101 

0107+312101 

010A+C32301 

010D+ 

0121+ @ENTSP: 

0123+C33401 

0126+5E 

0127+B7 

0128+CB 

0129+23 

012A+E5 

012B+0E0 2 

012D+CD0500 

013O+E1 

0131+C32601 

0134+213D01 

0137+CD2601 

013A+C36701 

013D+46524F4D20??0003: 

0167+217001 

016A+CD2601 

016D+C39B01 

0170+46524F4D20??0005: 

019B+21A401 

019E+CD2601 

01A1+C3CE01 

01A4+46524F4D20770007: 

01CE+2A2101 

01D1+F9 

01D2+C9 

01D3 


MACLIB MSGLIB ;INCLUDE THE MACRO LIBRARY 

ORG TPA ;ORIGIN AT THE TRANSIENT AREA 

USE THE MACRO LIBRARY TO TYPE TWO MESSAGES 

ENTCCP 10 ;ENTER PROGRAM, RESERVE 10 LEVEL STACK 

LXI H,0 

DAD SP 

SHLD @ENTSP 

LXI SP,@STACK 

JMP 770001 

DS 2*10 

DS 2 

TYPEOUT <THIS IS THE FIRST MESSAGE> 

JMP 770002 

MOV E,M 

ORA A 

RZ 

INX H 

PUSH H 

MVI C,TYPE 

CALL BDOS 

POP H 

JMP MSGOUT 

LXI H,770003 

CALL MSGOUT 

JMP 770004 

DB 'FROM CONSOLE: THIS IS THE FIRST MESSAGE•,CR,LF,0 
TYPEOUT <THIS IS THE SECOND MESSAGE> 

LXI H,770005 

CALL MSGOUT 

JMP 770006 

DB 'FROM CONSOLE: THIS IS THE SECOND MESSAGE',CR,LF,0 
TYPEOUT <THIS IS THE THIRD MESSAGE> 

LXI H,770007 

CALL MSGOUT 

JMP 770008 

DB 'FROM CONSOLE: THIS IS THE THIRD MESSAGE',CR,LF,0 
RETCCP ;RETURN TO THE CONSOLE COMMAND PROCESSOR 
LHLD 0ENTSP 

SPHL 
RET 
END 


Listing 6-2. 


A Sample Assembly Using the MACLIB Facility 
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Consider also the special macro statements used in Listing 6-1 
within the body of the ENTCCP macro. The LOCAL statement defines 
the label START within the macro body. Each LOCAL statement causes 
the macro assembler to construct a unique symbol starting with ?? 
each time it is encountered. Thus, multiple macro calls reference 
unique labels that do not interfere with one another. ENTCCP also 
contains a conditional assembly statement that uses the NUL 
operator; this tests whether a macro parameter has been supplied or 
not. In this case, the ENTCCP macro can be started by: 

ENTCCP 

with no actual parameter, resulting in a default stack size of 32 
bytes. The following sections give exact details and examples. 

The TYPEOUT macro is a more complicated example of macro use. 
Note that this macro contains a redefinition of itself within the 
macro body. The structure of TYPEOUT is 


TYPEOUT 

MACRO 

?MESSAGE 

TYPEOUT 

MACRO 

??MESSAGE 


ENDM 



ENDM 



where the outer definition of TYPEOUT completely encloses the inner 
definition. The outer definition is active upon the first 
invocation of TYPEOUT, but upon completion, the nested inner 
definition becomes active. 

To see the use of such a nested structure, consider the TYPEOUT 
macro. Each time it starts, TYPEOUT prints the message sent as an 
actual parameter at the console device. The typeout process, 
however, can be easily handled with a short subroutine. Upon the 
first invocation, include the subroutine inline. Then simply call 
this subroutine on subsequent invocations of TYPEOUT. Thus, the 
outer definition of TYPEOUT defines the utility subroutine and then 
redefines itself, so that the subroutine is called, rather than 
including another copy of the utility subroutine. 

Note that macro definitions are stored in the symbol table area 
of the assembler, so each macro reduces the remaining free space. 
MAC allows double semicolon comments to indicate that the comment 
itself is to be ignored and not stored with the macro. Thus, 
comments with a single semicolon are stored with the macro and 
appear in each expansion; comments with two preceding semicolons are 
listed only when the macro is defined. 

Listing 6-2 gives three examples of TYPEOUT invocations, with 
three messages that are sent as actual parameters. Note that the 
LOCAL statement causes a unique label to be created (??0002) in the 
place of PASTSUB, which is used to branch around the utility 
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subroutine included inline between addresses 0126H and 0133H. The 
utility subroutine is then called, followed by another jump around 
the console message, also included inline. However, subsequent 
invocations of TYPEOUT use the previously included utility 
subroutine to type their messages. 

Although this example concentrates all macro definitions in a 
separate macro library, macros are often defined in the mainline 
(.ASM) source program. In fact, many programs that use macros do 
not use the external macro library facility at all. 

The rest of this manual examines many applications of macros. 
Macro facilities can simplify the programming task by abstracting 
from the primitive assembly language levels. That is, you can 
define macros that provide more generalized functions that are 
allowed at the pure assembly language level, such as macro languages 
for a given application, improved control facilities, and general 
purpose operating systems interfaces. The remainder of this manual 
first introduces the individual macro forms, and then presents 
several uses of the macro facilities in realistic applications. 


End of Section 6 
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The simplest macro facilities involve the REPT (repeat), IRPC 
(indefinite repeat character), and IRP (indefinite repeat) macro 
groups. All these forms cause the assembler to reread portions of 
the source program under control of a counter or list of textual 
substitutions. These groups are listed below in order of increasing 
complexity. 


7.1 The REPT-ENDM Group 

The REPT-ENDM group is written as a sequence of assembly 
language statements starting with the REPT pseudo operation and 
terminated by an ENDM pseudo operation. The form is 

label: REPT expression 
statement-1 
statement-2 

statement-n 
label: ENDM 

where the labels are optional. The expression following the REPT is 
evaluated as a 16-bit unsigned count of the number of times that the 
assembler is to read and process statements 1 through n, enclosed 
within the group. 

Listing 7-1 shows an example of the use of the REPT group. In 
this case, the REPT-ENDM group generates a short table of the byte 
values 5, 4, 3, 2, and 1. Upon entry to the REPT, the value of 
NXTVAL is 5. This is taken as the repeat count, even though NXTVAL 
changes within the REPT. The macro lines that do not generate 
machine code are not listed in the repetition, while the lines that 
do generate code are listed with a + sign after the machine code 
address. Full macro tracing is optional, however, using assembly 
parameters. (See Section 10.) 
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CP/M MACRO ASSEM 2.0 


#001 SAMPLE REPT STATEMENT 


0100 


ORG 10OH ;BASE OF TRANSIENT AREA 
TITLE 'SAMPLE REPT STATEMENT' 

THIS PROGRAM READS INPUT PORT 0 AND INDEXES INTO A TABLE 
BASED ON THIS VALUE. THE TABLE VALUE IS FETCHED AND SENT 
TO OUTPUT PORT 0 


0005 

= 

MAXVAL 

EQU 

5 

0100 

DB00 

RLOOP; 

IN 

0 

0102 

FE05 


CPI 

MAXVAL 

0104 

D20001 


JNC 

RLOOP 

0107 

211401 


LXI 

H,TABLE 

010A 

5F 


MOV 

E , A 

010B 

1600 


MVI 

D, 0 

010D 

19 


DAD 

D 

010E 

7E 


MOV 

A ,M 

010F 

D300 


OUT 

0 

0111 

C30001 


JMP 

RLOOP 


LARGEST VALUE TO PROCESS 
READ THE PORT VALUE 
TOO LARGE? 

IGNORE INPUT IF INVALID 
ADDRESS BASE OF TABLE 
LOW ORDER INDEX TO E 
HIGH ORDER 00 FOR INDEX 
HL HAS ADDRESS OF ELEMENT 
FETCH TABLE VALUE FOR OUTPUT 
SEND TO THE OUTPUT PORT AND LOOP 
FOR ANOTHER INPUT 


GENERATE A TABLE OF VALUES MAXVAL,MAXVAL- 


0005 # 

NXTVAL 

SET 

TABLE: 

DB 

MAXVAL 

REPT 

NXTVAL 

;STAR! 
NXTVAL 
; FILL 

' COUNTER AT MAXVAL 

i 

ONE (MORE) ELEMENT 


NXTVAL 

SET 

ENDM 

NXTVAL- 

1;;AND 

DECREMENT 

FILL VALUE 

0114+05 


DB 

NXTVAL 

;FILL 

ONE (MORE) 

ELEMENT 

0115+04 


DB 

NXTVAL 

; FILL 

ONE (MORE) 

ELEMENT 

0116+03 


DB 

NXTVAL 

;FILL 

ONE (MORE) 

ELEMENT 

0117+02 


DB 

NXTVAL 

; FILL 

ONE (MORE) 

ELEMENT 

0118+01 

0119 


DB 

END 

NXTVAL 

;FILL 

ONE (MORE) 

ELEMENT 


Listing 7-1. A Sample Program Using the REPT Group 


If a label appears on the REPT statement, its value is the 
first machine code address that follows. This REPT label is not 
reread on each repetition of the loop. The optional label on the 
ENDM is reread on each iteration; thus constant labels, not 
generated through concatenation or with the LOCAL pseudo operation, 
generate phase errors if the repetition count is greater than 1. 

Properly nested macros, including REPTs, can occur within the 
body of the REPT-ENDM group. Further, nested conditional assembly 
statements are also allowed, with the added feature that 
conditionals beginning within the repeat group automatically 
terminate upon reaching the end of the macro expansion. Thus, IF 
and ELSE pseudo operations are not required to have their 
corresponding ENDIF when they begin within the repeat group, 
although the ENDIF is allowed. 
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7.2 The IRPC-ENDM Group 

Similar to the REPT group, the IRPC-ENDM group causes the 
assembler to reread a bounded set of statements, taking the form: 

label: IRPC identifier,character-list 
statement-1 
statement-2 

statement-n 
label: ENDM 

where the optional labels obey the same conventions as in the REPT- 
ENDM group. The identifier is any valid assembler name, not 
including embedded $ separators. Character list denotes a string of 
characters terminated by a delimiter (space, tab, end-of-line, or 
comment). 

The IRPC controls the reread process as follows: the statement 
sequence is read once for each character in the character list. On 
each repetition, a character is taken from the character list and 
associated with the controlling identifier, starting with the first 
and ending with the last character in the list. Thus, an IRPC 
header of the form 

IRPC ?X,ABCDE 

rereads the statement sequence that follows (to the balancing ENDM) 
five times, once for each character in the list ABCDE. On the first 
iteration, the character A is associated with the identifier ?X. On 
the fifth iteration, the letter E is associated with the controlling 
identifier. 

On each iteration, the macro assembler substitutes any 
occurrence of the controlling identifier by the associated character 
value. Using the preceding IRPC header, an occurrence of ?X in the 
bounds of the IRPC-ENDM group is replaced by the character A on the 
first iteration, and by E on the last iteration. 

The programmer can use the controlling identifier to construct 
new text strings within the body of the IRPC by using the special 
concatenation operator, denoted by an ampersand (&) character. 
Again using the preceding IRPC header, the macro assembler replaces 
LAB&7X with LABA on the first iteration. LABE is produced on the 
final iteration. The concatenation feature is most often used to 
generate unique label names on each iteration of the IRPC reread 
process. 

The controlling identifier is not usually substituted within 
string quotes because the controlling identifier can appear as a 
part of a quoted message. Thus, the macro assembler performs 
substitution of the controlling identifier when it is preceded or 
followed by the ampersand operator. Further, all alphabetics 
outside string quotes are translated to upper-case, but no case 
translation occurs within string quotes. So the controlling 
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identifier must not only be preceded or followed by the 
concatenation operator within strings, but it must also be typed in 
upper-case. 

Listings 7-2a and 7-2b illustrate the use of the IRPC-ENDM 
group. Listing 7-2a shows the original assembly language program, 
before processing by the macro assembler. The program is typed in 
both upper- and lower-case. Listing 7-2b shows the output from the 
macro assembler, with the lower-case alphabetics translated to 
upper-case. Three IRPC groups are shown in this example. The first 
IRPC uses the controlling identifier reg to generate a sequence of 
stack push operations that save the double-precision registers BC, 
DE, and HL. The lines generated by this group are marked by a + 
sign following the machine code address. 
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construct a data table 


7 save relevant registers 

enter: irpc 

reg,bdh 

push 

reg ;;save reg 

endm 


i 

7 initialize a partial ascii table 

irpc 

c,lAb$?@ 

data&c: db 

'&C* 

endm 


7 

; restore 

registers 

irpc 

reg,hdb 

pop 

reg ;;recall reg 

endm 


ret 


end 


Listing 7-2a. Original 

(.ASM) Pile with IRPC Example 



7 

CONSTRUCT A DATA TABLE 


7 

i 

SAVE RELEVANT REGISTERS 


ENTER: 

IRPC 

REG,BDH 



PUSH 

REG ?;SAVE REG 



ENDM 


0000+C5 


PUSH 

B 

0001+D5 


PUSH 

D 

0002+E5 


PUSH 

H 


7 

INITIALIZE A PARTIAL ASCII TABLE 



IRPC 

C,1AB$?@ 


DATA&C: 

DB 

'&C' 



ENDM 


0003+31 

DATA1: 

DB 

•1' 

0004+41 

DATAA: 

DB 

'A' 

0005+42 

DATAB: 

DB 

'B' 

0006+24 

DATA$: 

DB 


0007+3F 

DATA?: 

DB 

' ? ' 

0008+40 

DATA@: 

DB 



7 

7 

RESTORE 

REGISTERS 



IRPC 

REG,HDB 



POP 

REG ;;RECALL REG 



ENDM 


0009+El 


POP 

H 

000A+D1 


POP 

D 

000B+C1 


POP 

B 

000C C9 


RET 


000D 


END 


Listing 

7-2b. Resulting 

(.PRN) File with IRPC Example 


All Information Presented Here is Proprietary to Digital Research 

47 






Programmer's Utilities Guide 


7.2 The IRPC-ENDM Group 


The second IRPC shown in Listing 7-2a uses the controlling 
identifier C to generate a number of single-byte constants with 
corresponding labels. Although the controlling variable was typed 
in lower-case, it has been translated to upper-case during assembly. 
The string ' &C* occurs within the group and, because the controlling 
variable is enclosed in string quotes, it must occur next to an 
ampersand operator and be typed in upper-case for the substitution 
to occur properly. On each iteration of the IRPC, a label is 
constructed through concatenation, and a DB is generated with the 
corresponding character from the character list. 

Substitution of the controlling identifier by its associated 
value can cause infinite substitution if the controlling identifier 
is the Same as the character from the character list. For this 
reason, the macro assembler performs the substitution and then moves 
along to read the next segment of the program, rather than rereading 
the substituted text for another possible occurrence of the 
controlling identifier. Thus, an IRPC of the form 

IRPC C,1AC$?@ 


produces 


DAT AC: DB ' C' 

in place of the DB statement at the label DATAA in Listing 7-2b. 

The last IRPC restores the previously saved double-precision 
registers and performs the exact opposite function from the IPRC at 
the beginning of the program. 

When no characters follow the identifier portion of the IRPC 
header, the group of statements is read once, and the controlling 
identifier is deleted when it is read. It is replaced by the null 
string. 


7.3 The IRP-ENDM Group 

The IRP (indefinite repeat) functions like the IRPC, except 
that the controlling identifier can take on a multiple character 
value. The form of the IRP group is 

label: IRP identifier,<cl-l,cl-2,...,cl-n> 
statement-1 
statement-2 

statement-m 
label: ENDM 

where the optional labels obey the conventions of the REPT and IRPC 
groups. The identifier controls the iteration, as follows. On the 
first iteration, the character list given by cl-1 is substituted for 
the identifier wherever the identifier occurs in the bounded 
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statement group (statements 1 through m). On the second iteration, 
cl-2 becomes the value of the controlling identifier. Iteration 
continues in this manner until the last character list, denoted by 
cl-n, is encountered and processed. Substitution of values for the 
controlling identifier is subject to the same rules as in the IRPC. 
Note rules for substitution within strings and concatenation of text 
using the ampersand & operator. Controlling identifiers are always 
ignored within comments. 

Listing 7-3 gives several examples of IRP groups. The first 
occurrence of the IRP in Listing 7-3 is a typical use of this 
facility to generate a jump vector at the beginning of a program or 
subroutine. The IRP assigns label names (INITIAL, GET, PUT, and 
FINIS) to the controlling identifier ?LAB and produces a jump 
instruction for each label by rereading the IRP group, substituting 
the actual label for the formal name on each iteration. 

The second occurrence of the IRP group in Listing 7-3 points 
out substitution conventions within strings for both IRPC and IRP 
groups. The controlling identifier IS takes on the values A-ROSE 
and ? on the two iterations of the IRP group, respectively. 

The controlling identifier is replaced by the character lists 
in the two occurrences of &IS and IS& inside the string quotes 
because they are both adjacent to the ampersand operator. is& is 
not replaced because the controlling identifier is typed in lower¬ 
case, and there is no automatic translation to upper-case within 
strings. The occurrences of IS within the comments are not 
substituted. 

The last IRP group shows the effects of an empty character 
list. The value of the controlling identifier becomes the null 
string of symbols and, in the cases where ?X is replaced, produces 
the statement: 

DB ' ' 

DB produces no machine code and is therefore not listed in the macro 
expansion. The three statements 

DB '? x 1 DB ' ?X' DB 

appear in the expansions because the '?x' is typed in lower-case and 
thus is not replaced. The '?X' does not appear next to an ampersand 
in the string and is thus not replaced. In the last case, only one 
of the double ampersands is absorbed in the '&&7X&' string. Here, 
the two ampersands surrounding ?X are removed because they occur 
immediately next to the controlling identifier within the string. 
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Substitution rules outside of string quotes and comments are 
much less complicated; the controlling identifier is replaced by the 
current character-list value whenever it occurs in any of the 
statements within the group. The ampersand operator can be placed 
before or after the controlling identifier to cause the preceding or 
following text to be concatenated. 

The actual forms for the character lists (cl-1 through cl-n) 
are more general than stated here. In particular, bracket nesting 
is allowed, and escape sequences allow delimiters to be ignored. 
The exact details of character list forms are discussed in the macro 
parameter sections. 
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7 

CREATE 

A JUMP VECTOR USING THE 

IRP GROUP 


IRP 

?LAB,CINITIAL,GET,PUT,FINIS> 


JMP 

?LAB ;;GENERATE THE 

NEXT JUMP 


ENDM 



0000+C30C00 

JMP 

INITIAL 


0003+C34300 

JMP 

GET 


0006+C34600 

JMP 

PUT 


0009+C34900 

JMP 

FINIS 


7 

7 

INDIVIDUAL CASES 


INITIAL 

: 



000C 211200 

LXI 

H f CHRS 


00OF C35100 

JMP 

ENDCASE 


CHRS: 

IRP 

IS,<A-ROSE ,?> 



DB 

' &IS IS IS&' ;IS IS 

&IS 


DB 

1 &IS isn' 1 t is&' 



ENDM 



0012+412D524F53 

DB 

'A-ROSE IS A-ROSE' 

;IS IS &IS 

0022+412D524F53 

DB 

'A-ROSE isn* ' t is&' 


0032+3F20495320 

DB 

*? IS ?' ;IS IS 

&IS 

0038+3F2069736E 

DB 

1 ? isn''t is&' 


0043 C35100 GET: 

JMP 

ENDCASE 


0046 C35100 PUT: 

JMP 

ENDCASE 


0049 C35100 FINIS: 

JMP 

ENDCASE 



IRP 

?X,<> 



DB 

’Px' 



DB 

'PX* 



DB 

1 &PX* 



DB 

1 &PX&' 



DB 

1 &&PX&* 



ENDM 



004C+3F78 

DB 

'Px' 


004E+3F58 

DB 

’PX* 


0050+26 

DB 




ENDCASE: 

0051 C9 RET 

0052 END 

Listing 7-3. A Sample Program Using IRP 
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7.4 The EXITM Statement 

The EXITM pseudo operation can occur within the body of a 
macro. Upon encountering the EXITM statement, the macro assembler 
aborts expansion of the current macro level. The EXITM pseudo 
operation occurs in the context 

macro-heading 

statement-1 

label: EXITM 

statement-n 

ENDM 

where the label is optional, and macro-heading denotes the REPT, 
IRPC, or IRP group heading as described above. The EXITM statement 
can also be used with the MACRO group, as discussed in later 
sections. 

The EXITM statement usually occurs within the scope of a 
surrounding conditional assembly operation. If the EXITM occurs in 
the scope of a false conditional test, the statement is ignored, and 
macro expansion continues. If the EXITM occurs within the scope of 
a true conditional, the expansion stops where the EXITM is 
encountered. Assembly statement processing continues after the ENDM 
of the group aborted by the EXITM statement. 

Two examples of the EXITM statement are shown in Listing 7-4. 
This listing shows two IRPCs used to generate DB statements up to 
eight characters long. These IRPCs might occur within the context 
of another macro definition, such as in the generation of CP/M File 
Control Block (FCB) names. In both cases, the variable LEN counts 
the number of filled characters. If the count reaches eight 
characters, the EXITM statement is assembled under a true condition, 
and the IRPC stops expansion. 

The first IRPC generates the entire string SHORT because the 
length of the character list is less than eight characters. Each 
evaluation of LEN = 8 produces a false value, and the EXITM is 
skipped. This IRPC terminates by exhausting the character list 
through its five repetitions. 

The second IRPC stops generation at the eighth character of the 
list LONGSTRING when the conditional LEN EQ 8 produces a true value, 
resulting in assembly of the EXITM statement. Note that = and EQ 
are equivalent operators. The EXITM causes immediate termination of 
the expansion process. 

The second IRPC also contains a conditional assembly without 
the balancing ENDIF. In this case, the ENDIF is not required 
because the conditional assembly begins within the macro body. The 
ENDM serves the dual purpose of terminating unmatched IFs and 
marking the physical end of the macro body. 
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SAMPLE USE OF THE EXITM STATEMENT WITH THE IRPC MACRO 


THE FOLLOWING IRPC FILLS AN AREA OF MEMORY WITH AT MOST 
EIGHT BYTES OF DATA: 


0000 # 

LEN 

SET 

0 

;INITIALIZE LENGTH TO 0 



IRPC 

N,SHORT 




DB 

' &N 1 



LEN 

SET 

LEN+1 




IF 

LEN = 8 




EXITM 


;STOP MACRO IF AREA IS FULL 



ENDIF 





ENDM 



0000+53 


DB 

'S' 


0001+48 


DB 

'H* 


0002+4F 


DB 

'O' 


0003+52 


DB 

'R' 


0004+54 


DB 

1 rp 1 



0000 # 


0005+4C 

0006+4F 

0007+4E 

0008+47 

0009+53 

000A+54 

000B+52 

000C+49 


? 

LEN 


LEN 


THE FOLLOWING MACRO PERFORMS EXACTLY THE SAME FUNCTIONS 
SHOWN ABOVE , BUT ABORTS EXPANSION WHEN LENGTH EXCEEDS 8 


SET 

IRPC 

DB 

SET 

IF 

EXITM 

ENDM 

DB 

DB 

DB 

DB 

DB 

DB 

DB 

DB 


0 ;INITIALIZE LENGTH COUNTER 

N,LONGSTRING 

' &N 1 

LEN+1 

LEN EQ 8 


L 

O 

N 

G 

S 

T 

R 

I 


000D 


END 


Listing 7-4. Use of the EXITM Statement in Macro Processing 
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7.5 The LOCAL Statement 

It is often useful to generate labels for jumps or data 
references unique on each repetition of a macro. This facility is 
available through the LOCAL statement. The LOCAL statement takes 
the form 


macro-heading 

label: LOCAL id-1,id-2,. . .,id-n 
ENDM* 

where the label is optional, macro-heading is a REPT, IRPC, or IRP 
heading, already discussed, or a MACRO heading as discussed in 
following sections, and id-1 through id-n represent one or more 
assembly language identifiers that do not contain embedded $ 
separators. The LOCAL statement must occur within the body. It 
should appear immediately following the macro header to be 
compatible with the standard Intel macro facility. 

Upon encountering the LOCAL statement, the assembler creates a 
new frame of the form 

??nnnn 

for association with each identifier in the LOCAL list, where nnnn 
is a four-digit decimal value assigned in ascending order starting 
at 0001. Whenever the assembler encounters one of the identifiers 
in the list, the corresponding created name is substituted in its 
place. Substitution occurs according to the same rules as those for 
the controlling identifier in the IRPC and IRP groups. 

Avoid the use of labels that begin with the two characters ??, 
so that no conflicting names accidentally occur. Symbols that begin 
with ?? are not usually included in the sorted symbol list at the 
end of assembly. (See Section 10 to override this default.) A 
total of 9999 LOCAL labels can be generated in any assembly. An 
overflow error occurs if more generations are attempted. 

Listing 7-5a shows an example of a program using the LOCAL 
statement to generate both data references and jump addresses. This 
program uses the CP/M operating system to print a series of four 
generated messages, as shown in the output from the program in 
Listing 7-5b. 

The program begins with equates that define the operating 
system primary entry point, along with names for the nongraphic 
ASCII characters CR (carriage return) and LF (line-feed). The REPT 
statement that follows contains a LOCAL statement with the 
identifiers X and Y. These identifiers are used throughout the body 
of the REPT group. 

On the first iteration, X's value becomes ??0001, the first 
generated label; Y's value becomes ??0002. The substitution for X 
and Y within the generated strings follows the rules stated for 
controlling identifiers in previous sections. 
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Upon completion, four messages are generated along with four 
CALLS to the PRINT subroutine. At each call to PRINT, the message 
address is present in the DE register pair. The subroutine loads 
the print string function number into register C (C=9) and calls the 
operating system to print the string value. 


0100 


ORG 

100H 

;BASE OF THE TRANSIENT AREA 

0005 = 

BDOS 

EQU 

5 

;BDOS ENTRY POINT 

000D = 

CR 

EQU 

0DH 

;CARRIAGE RETURN (ASCII) 

000A = 

LF 

EQU 

0AH 

;LINE FEED (ASCII) 


7 

7 

SAMPLE 

PROGRAM 

SHOWING THE USE OF ’LOCAL' 


7 

REPT 

4 

.•REPEAT GENERATION 4 TIMES 



LOCAL 

X,Y 

;;GENERATE TWO LABELS 



JMP 

Y 

.•JUMP PAST THE MESSAGE 


X: 

DB 

'print 

x = &X. y= & Y',CR,LF,'$' 


Y: 

LXI 

D, X 

.•READY PRINT STRING 



CALL 

PRINT 




ENDM 



0100+C31E01 


JMP 

??0002 

.•JUMP PAST THE MESSAGE 

0103+7072696E74??0001: 

DB 

'print 

x=??0001, y=??0002',CR,LF,'$ 

011E+110301 

??0002: 

LXI 

D,??0001 ;READY PRINT STRING 

0121+CD9101 


CALL 

PRINT 


0124+C34201 


JMP 

??0004 

;JUMP PAST THE MESSAGE 

0127+7072696E74??0003: 

DB 

'print 

x=??0003, y=??0004',CR,LF,'$ 

0142+112701 

??0004: 

LXI 

D,??0003 ;READY PRINT STRING 

0145+CD9101 


CALL 

PRINT 


0148+C36601 


JMP 

??0006 

;JUMP PAST THE MESSAGE 

014B+707 2696E74?? 0005: 

DB 

'print 

x=??0005, y=??0006’,CR,LF,’$ 

0166+114B01 

??0006: 

LXI 

D,??0005 ;READY PRINT STRING 

0169+CD9101 


CALL 

PRINT 


016C+C38A01 


JMP 

??0008 

.•JUMP PAST THE MESSAGE 

016F+7072696E74??0007: 

DB 

'print 

x=??0007, y=??0008',CR,LF,'$ 

018A+116F01 

??0008: 

LXI 

D,??0007 ;READY PRINT STRING 

018D+CD9101 


CALL 

PRINT 


0190 C9 


RET 



0191 0E09 

PRINT: 

MVI 

C, 9 


0193 CD0500 


CALL 

BDOS 


0196 C9 


RET 



0197 


END 




Listing 7-5a. Assembly Program Using the LOCAL Statement 


All Information Presented Here is Proprietary to Digital Research 


55 



Programmer's Utilities Guide 


7.5 The LOCAL Statement 


print x=??0001, y=??0002 
print x=??0003, y=??0004 
print x=??0005, y=??0006 
print x=??0007 , y=??0008 


Listing 7-5b. Output from Program in Listing 7-5a 


Upon completion of the program, control returns to the Console 
Command Processor (CCP) for further operations. This program uses 
the default stack passed by the CCP. About 16 levels are available. 
This example is primarily intended to show operation of the LOCAL 
statement. Consult the CP/M documentation for BDOS interface 
conventions to follow this example completely. 


End of Section 7 
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Section 8 

Definition and Evaluation of Stored Macros 


The stored macro facility of MAC allows you to name a sequence 
of assembly language prototype statements to be included at selected 
places throughout the assembly process. Macro parameters can be 
supplied in various forms at the point of expansion which are 
substituted as the prototype statements are reread. These 
parameters tailor the macro expansion to a particular case. 

Although similar in concept to subroutine definition and call,, 
macro processing is purely textual manipulation at assembly time. 
That is, macro definitions cause source text to be saved in the 
assembler's internal tables, and any expansion involves manipulating 
and rereading the saved text. 

You can combine macro features in various ways to greatly 
enhance the available facilities. Specifically, you can 

o easily manipulate generalized data definitions 
o define macros for generalized operating systems interface 
o define simplified program control structures 
o support nonstandard instruction sets, such as the Z80® 

Finally, well-designed macros for an application can achieve a 
measure of machine independence. 


8.1 The MACRO-ENDM Group 

The prototype statements for a stored macro are given in the 
macro body enclosed by the MACRO and ENDM pseudo operations, taking 
the general form 

macname MACRO d-l,d-2,. . .,d-n 

statement-1 
statement-2 
• • • 

statement-m 
label: ENDM 

where the macname is any nonconflicting assembly language 
identifier; d-1 through d-n constitutes a (possibly empty) list of 
assembly identifiers without embedded $ separators, and statement-1 
through statement-m are the macro prototype statements. The 
identifiers denoted by d-1 through d-n are called dummy parameters 
for this macro. Although they must be unique within the macro body, 
dummy parameters can be identical to any program identifiers outside 
the macro body without causing a conflict. The prototype statements 
can contain any properly balanced assembly language statements or 
groups, including nested REPTs, IRPCs, MACROS, and IFs. 
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The prototype statements are read and stored in the assembler's 
internal tables under the name give by macname. They are not 
processed until the macro is expanded. The following section gives 
the expansion process. 

The label preceding the ENDM is optional. 


8.2 Calling a Macro 

The macro text stored through a MACRO-ENDM group can be brought 
out for processing through a statement of the form 

label: macname a-l,a-2,. . .,a-n 

where the label is optional, and macname has previously occurred as 
the identifier on a MACRO heading. The actual parameters a-1 
through a-n are sequences of characters separated by commas and 
terminated by a comment or end-of-line. 

Upon recognition of the macname, the assembler first pairs off 
each dummy parameter in the MACRO heading (d-1 through d-n) with the 
actual parameter text (a-1 through a-n). The assembler associates 
the first dummy parameter with the first actual parameter (d-1 is 
paired with a-1), the second dummy with the second actual, and so 
forth until the list is exhausted. If more actuals are provided 
than dummy parameters, the extras are ignored. If fewer actuals are 
provided, then the extra dummy parameters are associated with the 
empty string (a text string of zero length). The value of a dummy 
parameter is not a numeric value, but is instead a textual value 
consisting of a sequence of zero or more ASCII characters. 

After each dummy parameter is assigned an actual textual value, 
the assembler rereads and processes the previously stored prototype 
statements and substitutes each occurrence of a dummy parameter by 
its associated actual textual value, according to the same rules as 
the controlling identifier in an IRPC or IRP group. 

Listings 8-1 and 8-2 provide examples of macro definitions and 
invocations. Listing 8-1 begins with the definition of three 
macros, SAVE, RESTORE, and WCHAR• The SAVE macro contains prototype 
statements that save the principal CPU registers (PUSH PSW, B, D, 
and H) . The RESTORE macro restores the principal registers (POP H, 
D, B, and PSW). The WCHAR macro contains the statements necessary 
to write a single character at the console using a CP/M BDOS call. 

The occurrence of the SAVE macro definition between MACRO and 
ENDM causes the assembler to read and save the PUSHs, but does not 
assemble the statements into the program. Similarly, the statements 
between the RESTORE MACRO and the corresponding ENDM are saved, as 
are the statements between the WCHAR MACRO and ENDM statements. The 
fact that the assembler is reading the macro definition is indicated 
by the blank columns in the leftmost 16 columns of the output 
listing. 
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Referring to Listing 8-1, note that machine code generation 
starts following the SAVE macro call. The prototype statements that 
were previously stored are reread and assembled, with a + between 
the machine code address and the generated code to indicate that the 
statements are being recalled and assembled from a macro definition. 
The SAVE macro has no dummy parameters in the definition, so no 
actual parameters are required at the point of invocation. 

The SAVE call is immediately followed by an expansion of the 
WCHAR macro. The WCHAR macro, however, has one dummy parameter, 
called CHR, which is listed in the macro definition header. This 
dummy parameter represents the character to pass to the BDOS for 
printing. In the first expansion of the WCHAR macro, the actual 
parameter H becomes the textual value of the dummy parameter CHR. 
Thus, the WCHAR macro expands with a substitution of the dummy 
parameter CHR by the value H. The CHR is within string quotes, so 
it is typed in upper-case and preceded by the ampersand operator. 
Following the reference to WCHAR, the prototype statements are 
listed with the + sign to indicate that they are generated by the 
macro expansion. 
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0100 


ORG 

10OH ;BASE OF TRANSIENT AREA 

0005 = 

BDOS 

EQU 

5 ;BDOS ENTRY POINT 

0002 = 

CONOUT 

EQU 

2 ;CHARACTER OUT FUNCTION 


SAVE 

MACRO 

PUSH 

PUSH 

PUSH 

PUSH 

ENDM 

;SAVE ALL CPU REGISTERS 

PSW 

B 

D 

H 


RESTORE MACRO 
POP 

POP 

POP 

POP 

ENDM 

;RESTORE ALL REGISTERS 

H 

D 

B 

PSW 


WCHAR 

MACRO 

MV I 

MV I 

CALL 

ENDM 

CHR ;WRITE CHR TO CONSOLE 

C,CONOUT ;;CHAR OUT FUNCTION 

E , 1 &CHR' ;;CHAR TO SEND 

BDOS 


7 

7 

MAIN PROGRAM STARTS HERE 

SAVE ;SAVE REGISTERS UPON ENTRY 

0100+F5 


PUSH 

PSW 

0101+C5 


PUSH 

B 

0102+D5 


PUSH 

D 

0103+E5 


PUSH 

WCHAR 

H 

H ;SEND , H' TO CONSOLE 

0104+0E02 


MV I 

C,CONOUT 

0106+1E48 


MV I 

E , 1 H' 

0108+CD0500 


CALL 

WCHAR 

BDOS 

I ;SEND * I' TO CONSOLE 

010B+0E02 


MV I 

C,CONOUT 

010D+1E49 


MVI 

E, 1 1* 

010F+CD0500 


CALL 

RESTORE 

BDOS 

;RESTORE CPU REGISTERS 

0112+E1 


POP 

H 

0113+Dl 


POP 

D 

0114+C1 


POP 

B 

0115+F1 


POP 

PSW 

0116 C9 

0117 


RET 

END 

;RETURN TO CCP 


Listing 8-1. Example of Macro Definition and Invocation 
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The second invocation of WCHAR is similar to the first except 
that the dummy parameter CHR is assigned the textual value I, 
causing generation of a MVI E,'I' for this case. 

After the listing of the second WCHAR expansion, the RESTORE 
macro starts, causing generation of the POP statements to restore 
the register state. The RESTORE is followed by a RET to return to 
the CCP following the character output. 

This program saves the registers upon entry, typing the two 
characters HI at the console, restoring the registers, and then 
returning to the Console Command Processor. The SAVE and RESTORE 
macros are used here for illustration and are not required for 
interface to the CCP, since all registers are assumed to be invalid 
upon return from a user program. Further, this program uses the CCP 
stack throughout. This stack is only eight levels deep. 

Listing 8-2 shows another macro for printing at the console. 
In this case, the PRINT macro uses the operating system call that 
prints the entire message starting at a particular address until the 
$ symbol is encountered. The PRINT macro has a slightly more 
complicated structure: two dummy parameters must be supplied in the 
invocation. The first parameter, called N, is a count of the number 
of carriage return line-feeds to send after the message is printed. 
The second parameter, called MESSAGE, is the ASCII string to print 
that must be passed as a quoted string in the invocation. 

The LOCAL statement within the macro generates two labels 
denoted by PASTM and MSG. When the macro expands, substitutions 
occur for the two dummy parameters by their associated actual 
textual values, and for PASTM and MSG by their sequentially 
generated label values. The macro definition contains prototype 
statements that branch past the message (to PASTM) that is included 
inline following the label MSG. The message is padded with N pairs 
of carriage return line-feed sequences, followed by the $ that marks 
the end of the message. The string address is then sent to the BDOS 
for printing at the console. 

Listing 8-2 includes two invocations of the PRINT macro. The 
invocation sends two actual parameters: the textual value 2 is 
associated with the dummy N, followed by a quoted string associated 
with the dummy parameter MSG. The second actual parameter includes 
the string quotes as a part of the textual value. The generated 
message is preceded by a jump instruction and followed by N = 2 
carriage return line-feed pairs. 

The second invocation of the PRINT macro is similar to the 
first, except that the REPT group is executed N = 0 times, resulting 
in no carriage return line-feed pairs. 

Similar to Listing 8-1, the program of Listing 8-2 uses the 
Console Command Processor's eight-level stack for the BDOS calls. 
When the program executes, it types the two messages, separated by 
two lines, and returns to the CCP. 
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0100 


ORG 

100H ;BASE OF THE TPA 


0005 = 

BDOS 

EQU 

5 ;BDOS ENTRY POINT 


0009 = 

PMSG 

EQU 

9 ;PRINT ’TIL $ FUNCTION 

000D = 

CR 

EQU 

0DH ;CARRIAGE RETURN 


000A = 

LF 

EQU 

0AH ;LINE FEED 



PRINT 

MACRO 

N,MESSAGE 



7 7 

PRINT 

MESSAGE, FOLLOWED BY N CRLF' 

S 


LOCAL 

PASTM, 

MSG 



JMP 

PASTM 

;;JUMP PAST MSG 



MSG: 

DB 

MESSAGE ;;INCLUDE TEXT TO 

WRITE 


REPT 

N 

;;REPEAT CR LF SEQUENCE 



DB 

CR,LF 





ENDM 




DB 

’$’ 

;;MESSAGE TERMINATOR 



PASTM: 

LXI 

D,MSG ;;MESSAGE ADDRESS 




MV I 

C,PMSG 77 PRINT FUNCTION 




CALL 

BDOS 




ENDM 




7 

PRINT 

2,’The rain in Spain goes 

i 

0100+C31E01 


JMP 

??0001 


0103+5468652072??0002: 

DB 

’The rain in Spain goes’ 


0119+0D0A 


DB 

CR,LF 


011B+0D0A 


DB 

CR,LF 


011D+24 


DB 



011E+110301 

??0001: 

LXI 

D, ??0002 


0121+0E09 


MVI 

C,PMSG 


0123+CD0500 


CALL 

BDOS 




PRINT 

0,'mainly down the drain. 

i 

0126+C34001 


JMP 

??0003 


0129+6D61696E6C770004: 

DB 

'mainly down the drain.' 


013F+24 


DB 



0140+112901 

770003: 

LXI 

D/??0004 


0143+0E09 


MVI 

C,PMSG 


0145+CD0500 


CALL 

BDOS 


0148 C9 


RET 




Listing 8-2. Sample Message Printout Macro 
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8.3 Testing Empty Parameters 

The NUL operator is specifically designed to allow testing of 
null parameters. Null parameters are actual parameters of length 
zero. NUL is used as a unary operator. NUL produces a true value 
if its argument is of length zero and a false value if the argument 
has a length greater than zero. Thus the operator appears in the 
context of an arithmetic expression as: 

. . . NUL argument 

where the ellipses (. . .) represent an optional prefixing 
arithmetic expression, and argument is the operand used in the NUL 
test. The NUL differs from other operators because it must appear 
as the last operator in the expression. This is because the NUL 
operator absorbs all remaining characters in the expression until 
the following comment or end-of-line is found. Thus, the expression 

X GT Y AND NUL XXX 

is valid because NUL absorbs the argument XXX, producing a false 
value in the scan for the end-of-line. The expression 

X GT Y AND NUL M +Z) 

is deceiving but nevertheless valid, even though it appears to be an 
unbalanced expression. In this case, the argument following the NUL 
operator is the entire sequence of characters M + Z) . This sequence 
is absorbed by the NUL operator in scanning for the end-of-line. 
The value of NUL M + Z) is false because the sequence is not empty. 

Listing 8-3 gives several examples of the use of NUL in a 
program. In the first case, NUL returns true because there is an 
empty argument following the operator. Thus, the true case is 
assembled, as indicated by the machine code to the left, and the 
false case is ignored. Similarly, the second use of NUL in Listing 
8-3 produces a false value because the argument is nonempty. Both 
uses of NUL, however, are contrived examples, because NUL is only 
useful within a macro group, as shown in the definition of the 
NULMAC macro. 

NULMAC consists of a sequence of three conditional tests that 
demonstrate the use of NUL in checking empty parameters. In each of 
the tests, a DB is assembled if the argument is not empty and 
skipped otherwise. Seven invocations of NULMAC follow its 
definition, giving various combinations of empty and nonempty actual 
parameters. 

In the first case, NULMAC has no actual parameters. Thus all 
dummy parameters (A, B, and C) are assigned the empty sequence. As 
a result, all three conditional tests produce false results because 
both A and B are empty; B&C concatenates two empty sequences, 
producing an empty sequence as a result. 
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The second invocation of NULMAC provides only one actual 
parameter, XXX, assigned to the dummy parameter A. B and C are both 
assigned the empty sequence. Thus only the DB for the first 
conditional test is assembled. 



IF 

NUL 

0000 7472756520 

DB 

’true case* 


ELSE 

DB 

END IF 

’false case’ 

7 

IF 

NUL XXX 


DB 

ELSE 

'xxx is nul* 

0009 7878782069 

DB 

ENDIF 

'xxx is not nul* 

NULMAC 

MACRO 

A,B,C 


IF 

NOT NUL A 


DB 

ENDIF 

*a = &A is not nul* 


IF 

NOT NUL B 


DB 

ENDIF 

*b = &B is not nul* 


IF 

NOT NUL B&C 


DB 

ENDM 

* be = &B&C is not nul* 

7 

NULMAC 

NULMAC 

XXX 

0017+61203D2058 

DB 

’a = XXX is not nul* 


NULMAC 

,xxx 

0029+62203D2058 

DB 

* b = XXX is not nul* 

003B+6263203D20 

DB 

*bc = XXX is not nul* 


NULMAC 

XXX,,YYY 

004F+61203D2058 

DB 

’a = XXX is not nul* 

0061+6263203D20 

DB 

* be = YYY is not nul* 


NULMAC 

, , YYY 

0075+6263203D20 

DB 

* be = YYY is not nul* 


NULMAC 

t t ! 


NULMAC 

II II 

r t 

0089+6263203D20 

DB 

* be = * * * * is not nul* 

009C 

END 


Listing 8-3. 

Sample Program Using the NUL Operator 
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The third case is similar to the second, except that the actual 
parameters for A and C are omitted. Thus, the second and third 
conditionals both test NOT NUL XXX, which is true because B has the 
value XXX, and B&C produces the value XXX as well. 


The fourth invocation of NULMAC skips the actual parameter for 
B but supplies values for both A and C. Thus, the first and third 
test result in true values? the second conditional group is skipped. 

The fifth invocation provides an actual parameter only for C. 
As a result, only the third conditional is true because B&C produces 
the sequence YYY. 


The sixth invocation produces exactly the same result as the 
first because all three actual parameters are empty. 

The final expansion of NULMAC in Listing 8-3 shows a special 
case of the NUL operator. The expression 

NUL ' ' 

where the two apostrophes are in juxtaposition, produces the value 
true, even though there are two apostrophe symbols on the line 
following NUL and before the end-of-line. The value of A is the 
empty string in this case. The value assigned to both B and C 
consists of the two apostrophe characters side by side; this is 
treated as a quoted string of length zero, even though it is a 
sequence of two characters. In this last expansion, the first 
conditional, however, evaluates the form 

NOT NUL '' 

that is the special case of NUL applied to a length zero quoted 
string, but not a length zero sequence. Because of the special 
treatment of the length zero quoted string, this expression also 
produces a false result. The third conditional, however, must be 
considered carefully. The original expression in the macro 
definition takes the form 

NOT NUL B&C 

with B and C both associated with the sequence of length two given 
by two adjacent apostrophes. Thus, the macro assembler examines 

NOT NUL " & " 

or, after concatenation, 

NOT NUL '''' 

where the four apostrophes are adjacent. Considering only the four 
apostrophes, the macro assembler considers this a quoted string that 
happens to contain a single apostrophe because double apostrophes 
are always reduced to a single apostrophe. As a result, the test 
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produces a true value, and the conditional segment is assembled. 
Usually the NUL operator is used only to test for missing arguments, 
as shown in later examples. (See Listing 8-6.) 


8.4 Nested Macro Definitions 

The MAC assembler allows you to include nested macro 
iefinitions. These take the form 

macl MACRO macl-list 

mac2 MACRO mac2-list 

ENDM 

ENDM 

where macl is the identifier corresponding to the outer macro, and 
mac2 is an identifier corresponding to an inner nested macro that is 
wholly contained within the outer macro. In this case, macl—list 
and mac2-list correspond to the dummy parameter lists for macl and 
mac2, respectively. As before, labels are allowed on the ENDM 
statements. 

The statements contained within a macro definition are 
prototype statements that are read and stored by the assembler but 
not evaluated as assembly language statements until the macro is 
expanded. Thus, in the preceding form, only the macl macro is 
available for expansion because the assembler has stored but not 
processed the body of macl that contains the definition of mac2. 
mac2 cannot be expanded until macl is first expanded, revealing the 
definition of mac2. 

Properly balanced embedded macros of this form can be nested to 
any level, but they cannot be referenced until their encompassing 
macros have themselves been expanded. 

Listing 8-4 gives a practical example of nested macro 
definition and expansion. This program writes characters either to 
the CP/M console device or to the currently assigned list device, 
according to the value of the LISTDEV flag set for the assembly. If 
the LISTDEV flag is true, then the assembly sends characters to the 
listing device. Otherwise, the console is used for output. In 
either case, the macro OUTPUT is produced; this sends a single 
character to the selected device. 

The sample program in Listing 8-4 uses the macro SETIO to 
construct the OUTPUT macro. The OUTPUT macro is wholly contained 
within the SETIO macro and, as a result, remains undefined until 
SETIO is expanded. Upon encountering the invocation of SETIO, the 
macro assembler reads the prototype statements within SETIO and, in 
the process, constructs the definition of the OUTPUT macro. Because 
LISTDEV is true for this assembly, the OUTPUT macro is defined as 
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OUTPUT 


MACRO 

CHAR 

MV I 

E,CHAR 

MV I 

C,LISTOUT 

CALL 

BDOS 

ENDM 



Note that the SETIO macro itself uses this newly created OUTPUT 
macro in its last prototype statement to print a single + at the 
selected device. 

Following the invocation of SETIO, the invocations of OUTPUT are 
recognized because its definition has been entered in the process 
of reading the prototype statements of SETIO. These invocations 
send the characters 1 and 2 to the list device. 
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0100 


ORG 

10OH ;BASE OF THE TPA 

0000 = 

FALSE 

EQU 

0000H ;VALUE OF FALSE 

FFFF = 

TRUE 

EQU 

NOT FALSE ;VALUE OF TRUE 


7 

LISTDEV 

IS TRUE IF LIST DEVICE IS USED 


7 

FOR OUTPUT, AND FALSE IF CONSOLE IS USED 

FFFF = 

LISTDEV 

7 

EQU 

TRUE 

0005 = 

BDOS 

EQU 

5 ;BDOS ENTRY POINT 

0002 = 

CONOUT 

EQU 

2 ;WRITE TO CONSOLE 

0005 = 

LISTOUT 

EQU 

5 ;WRITE TO LIST DEVICE 


SETIO 

MACRO 

?SETUP OUTPUT MACRO FOR LIST OR CONSOLE 


OUTPUT 

MACRO 

CHAR 



MVI 

E,CHAR ;;READY THE CHARACTER FOR PRINTING 



IF 

LISTDEV 



MVI 

C,LISTOUT 



ELSE 




MVI 

C,CONOUT 



ENDIF 




CALL 

BDOS 



ENDM 




OUTPUT 

»* i 



ENDM 



7 

SETIO 

;SETUP THE IO SYSTEM 

0100+1E2A 


MVI 

E, 

0102+0E05 


MVI 

C,LISTOUT 

0104+CD0500 


CALL 

BDOS 



OUTPUT 

'1' 

0107+1E31 


MVI 

E, ' 1' 

0109+0E05 


MVI 

C,LISTOUT 

010B+CD0500 


CALL 

BDOS 



OUTPUT 

'2' 

010E+1E32 


MVI 

E,' 2' 

0110+0E05 


MVI 

C,LISTOUT 

0112+CD0500 


CALL 

BDOS 

0115 C9 


RET 


0116 


END 


Listing 8-4. Sample Program Showing a Nested Macro Definition 
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8.5 Redefinition of Macros 

It is often useful to redefine the prototype statements of a 
macro after the initial prototype statements have been entered. 
Redefinition is a specific instance of the nesting described in the 
previous section, where the inner nested macro carries the same name 
as the encompassing macro definition. Macro redefinition is 
extremely useful if the macro contains a subroutine. In this case, 
the subroutine can be included on the first expansion and simply 
called in any remaining expansions. Thus, if the macro is never 
invoked, the subroutine is not included in the program. 

Listing 8-5 shows an example of macro redefinition. This 
sample program defines the macro MOVE. MOVE is intended to move 
byte values from a starting source address to a target destination 
address for a particular number of bytes. The three dummy 
parameters denote these three values: SOURCE is the starting 
address; DEST is the destination address, and COUNT is the number of 
bytes to move (a constant in the range 0-65535) . The actions of the 
MOVE macro, however, are complicated enough to be performed through 
a subroutine, rather than inline machine code each time MOVE is 
expanded. 

Examining the structure of MOVE in Listing 8-5, note that it 
contains a properly nested redefinition of MOVE, taking the general 
form: 


MOVE MACRO SOURCE,DEST,COUNT 

@MOVE subroutine 
MOVE MACRO ?S,?D,?C 

call to @MOVE 
ENDM 

invocation of MOVE 
ENDM 

Upon encountering the first invocation of MOVE, the assembler begins 
reading the prototype statements. Note, however, that the first 
expansion of the MOVE includes the subroutine for the actual move 
operation, labeled by @MOVE so that there is no name conflict (with 
a branch around the subroutine). MOVE then redefines itself as a 
sequence of statements that simply call the out-of-line subroutine 
each time it expands. The last statement of the original MOVE macro 
is an invocation of the newly defined version. As indicated by this 
example, once a macro has started expansion, it continues to 
completion (or until EXITM is assembled), even if it redefines 
itself. 
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0100 


ORG 10OH ;BASE OF TPA 

MOVE MACRO SOURCE,DEST,COUNT 

;; MOVE DATA FROM ADDRESS GIVEN BY ’SOURCE' 

;; TO ADDRESS GIVEN BY ’DEST' FOR ’COUNT’ BYTES 

LOCAL PASTSUB ;;LABEL AT END OF SUBROUTINE 


JMP PASTSUB ;;JUMP AROUND INLINE SUBROUTINE 

0MOVE: ;;INLINE SUBROUTINE TO PERFORM MOVE OPERATION 

;; HL IS SOURCE, DE IS DEST, BC IS COUNT 


MOV 

ORA 

RZ 

MOV 

STAX 

INX 

INX 

DCX 

JMP 


A ,C 
B 

A,M 

D 

H 

D 

B 

@MOVE 


;LOW ORDER COUNT 
;ZERO COUNT? 

;STOP MOVE IF ZERO REMAINDER 
;GET NEXT SOURCE CHARACTER 
;PUT NEXT DEST CHARACTER 
;ADDRESS FOLLOWING SOURCE 
;ADDRESS FOLLOWING DEST 
;COUNT=COUNT-1 
;FOR ANOTHER BYTE TO MOVE 


PASTSUB: 
MOVE 


ARRIVE HERE ON FIRST 


INVOCATION - REDEFINE MOVE 
;;CHANGE PARM NAMES 
;;ADDRESS THE SOURCE STRING 
;;ADDRESS THE DEST STRING 
;;PREPARE THE COUNT 
;;MOVE THE STRING 


MACRO ?S,?D,?C 

LXI H,?S 

LXI D,?D 

LXI B,?C 

CALL @MOVE 

ENDM 

CONTINUE HERE ON THE FIRST INVOCATION TO USE 
THE REDEFINED MACRO TO PERFORM THE FIRST MOVE 



MOVE 

ENDM 

SOURCE,DEST,COUNT 

t 

MOVE 

X1,X2,5 ;MOVE 5 CHi 

0100+C30E01 

JMP 

??0001 

0103+79 

MOV 

A ,C 

0104+B0 

ORA 

B 

0105+C8 

RZ 


0106+7E 

MOV 

A ,M 

0107+12 

STAX 

D 

0108+23 

INX 

H 

0109+13 

INX 

D 

010A+0B 

DCX 

B 

010B+C30301 

JMP 

@MOVE 

010E+212701 

LXI 

H, XI 

0111+114001 

LXI 

D,X2 

0114+010500 

LXI 

B, 5 

0117+CD0301 

CALL 

@MOVE 


MOVE 

300OH,100OH,150OH 

011A+210030 

LXI 

H,3000H 

011D+110010 

LXI 

D,1000H 

0120+010015 

LXI 

B,1500H 

0123+CD0301 

CALL 

0MOVE 

0126 C9 

RET 

;RETURN TO 

0127 6865726520X1: 

DB 

’here is some data 

0140 7878787878X2: 

DB 

'xxxxxwe areI' 


;BIG MOVER 


Listing 8-5. Sample Program Showing Macro Redefinition 
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It is important to note the use of ?S, ?D, and ?C in the 
previous example. The innermost MOVE macro uses the same sequence 
of three parameters for the source, destination, and count. The 
dummy parameter names must differ, however, because they would be 
substituted by their actual values if they were the same. This is 
because the inner MOVE macro is wholly contained within the outer 
macro, so parameter substitution takes place regardless of the 
context. 

Macro storage is not reclaimed upon definition, however, 
because the macro assembler performs two passes through the source 
program and saves any preceding definitions for the second pass 
scan. 


8.6 Recursive Macro Invocation 

The prototype statements of a recursive macro x contain 
invocations of macros that, in turn, invoke macros that eventually 
lead back to an invocation of x. A direct recursion occurs when x 
invokes itself, as shown in the form below: 

macname MACRO d-1,. . . ,d-n 
macname a-1,. . .,a-n 
ENDM 

Although this form is similar to the embedded macro definition 
discussed in the previous section, macname is expanded within its 
own definition, rather than being redefined. Recursion is only 
useful, however, in the presence of conditional assembly where 
various tests are made that prevent infinite recursion. In fact, 
recursion is allowed only to sixteen levels before returning to 
complete the expansion of an earlier level. 

Listing 8-6 shows a situation in which indirect recursive macro 
invocation is useful. The macro WCHAR writes a character to the 
console device using the general purpose operating system macro 
CBDOS (call BDOS). CBDOS acts as an interface between the program 
and the CP/M system by performing the system function given by FUNC, 
with optional information address INFO. CBDOS loads the specified 
function to register C, then tests to see whether the INFO argument 
has been supplied, using the NUL operator. If supplied, INFO is 
loaded to the DE register pair. After register setup, the BDOS is 
called, and the macro has completed its expansion. 

Assume, however, that CBDOS has the additional task of 
inserting a carriage return line-feed before writing messages where 
operating system Function 9 (write buffer until $) has been 
specified. In this case, CBDOS uses the WCHAR macro to send the 
carriage return line-feed. The WCHAR macro, in turn, uses CBDOS to 
send the character, resulting in two activations of CBDOS at the 
same time. The assembler holds the initial invocation of CBDOS 
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until the WCHAR macro has completed, then returns to complete the 
initial CBDOS expansion. 

In recursion the values of the dummy parameters are saved at 
each successive level of recursion and restored when that level of 
recursion is reinstated. Reentry into a macro expansion through 
recursion does not destroy the values of dummy arguments held by 
previous entry levels. 
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0100 


ORG 

100H ;BASE OF TRANSIENT AREA 


7 

SAMPLE PROGRAM SHOWING RECURSIVE MACROS 

0005 = 

BDOS 

EQU 

0005H ;ENTRY TO BDOS 

0002 = 

CONOUT 

EQU 

2 ;CONSOLE CHARACTER OUT 

0009 = 

MSGOUT 

EQU 

9 ;PRINT MESSAGE 'TIL $ 

00OD = 

CR 

EQU 

0DH ;CARRIAGE RETURN 

000A = 

LF 

EQU 

0AH ;LINE FEED 


WCHAR 

MACRO 

CHR 


7 7 

WRITE 

THE CHARACTER CHR TO CONSOLE 



CBDOS 

CONOUT,CHR ;;CALL BDOS 



ENDM 



CBDOS 

MACRO 

FUNC,INFO 


7 7 

GENERAL PURPOSE BDOS CALL MACRO 


7 7 

FUNC 

IS THE FUNCTION NUMBER, 


7 7 

INFO : 

IS THE INFORMATION ADDRESS OR NUL 


7 7 

CHECK 

FOR FUNCTION 9, SEND CRLF FIRST IF S 



IF 

FUNC=MSGOUT 


7 7 

PRINT 

CRLF FIRST 



WCHAR 

CR 



WCHAR 

LF 



ENDIF 



7 7 

NOW PERFORM THE FUNCTION 



MVI 

C,FUNC 


7 7 

INCLUDE LXI TO DE IF INFO NOT EMPTY 



IF 

NOT NUL INFO 



LXI 

D,INFO 



ENDIF 




CALL 

BDOS 



ENDM 



7 

WCHAR 

'h' ;SEND "H" TO CONSOLE 

0100+0E02 


MVI 

C,CONOUT 

0102+116800 


LXI 

D, 1 h 1 

0105+CD0500 


CALL 

BDOS 



WCHAR 

1 i' ;SEND 'I 1 TO CONSOLE 

0108+0E02 


MVI 

C,CONOUT 

010A+116900 


LXI 

D, 1 i' 

010D+CD0500 


CALL 

BDOS 



CBDOS 

MSGOUT,MSGADDR ;SEND MESSAGE 

0110+0E02 


MVI 

C,CONOUT 

0112+11ODO0 


LXI 

D,CR 

0115+CD0500 


CALL 

BDOS 

0118+0E02 


MVI 

C,CONOUT 

011A+110A00 


LXI 

D, LF 

011D+CD0500 


CALL 

BDOS 

0120+0S09 


MVI 

C,MSGOUT 

0122+112901 


LXI 

D,MSGADDR 

0125+CD0500 


CALL 

BDOS 

0128 C9 


RET 

;TERMINATE PROGRAM 


MSGADDR 



0129 616E64206C 

DB 

'and lois$* 

0132 


END 



Listing 8-6. Sample Program Showing a Recursive Macro 
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8.7 Parameter Evaluation Conventions 

You can exercise a number of options in the construction of 
actual parameters, and in the specification of character lists for 
the IRP group. Although an actual parameter is simply a sequence of 
characters placed between parameter delimiters, these options allow 
overrides where delimiter characters themselves become a part of the 
text. A parameter x occurs in the context: 

label: macname <. . ., x , . . •> 

where macname is the name of a previously defined macro, and the 
preceding label is optional. The ellipses . . . represent optional 
surrounding actual parameters in the invocation of macname. In the 
case of an IRP group, the occurrence of a character list x is 

label: IRP id,. . •, x ,. . . 

where the label is again optional, and the ellipses represent 
optional surrounding character lists for substitution within the IRP 
group where the controlling identifier id is found. In either case, 
the statements can be contained within the scope of a surrounding 
macro expansion. Hence, dummy parameter substitution can take place 
for the encompassing macro while the actual parameter is being 
scanned. 

The macro assembler follows the steps shown below in forming an 
actual parameter or character list: 


1) Leading blanks and tabs (control-I) are removed if they 
occur in front of x. 

2) The leading character of x is examined to determine the type 
of scan operation to take place. 

3) If the leading character is a string quote (apostrophe), 
then x becomes the text up to and including the balancing 
string quote, using the normal string scanning rules: 
double apostrophes within the string are reduced to a 
single apostrophe, and upper-case dummy parameters adjacent 
to the ampersand symbol are substituted by the actual 
parameter values. Note that the string quotes on either 
end of the string are included in the actual parameter 
text. 

4) If the first character is the left angle bracket (<), then 
the bracket is removed, and the value of x becomes the 
sequence of characters up to, but not including, the 
balancing right angle bracket (>). The right angle bracket 
does not become a part of x. In this case, left and right 
angle brackets can be nested to any level within x, and 
only the outer brackets are removed in the evaluation. 
Quoted strings within the brackets are allowed, and 
substitution within these strings follows the rules stated 


All Information Presented Here is Proprietary to Digital Research 


74 





Programmer's Utilities Guide 


8.7 Parameter Evaluation 


in 3) above. Left and right brackets within quoted strings 
become a part of the string; these are not counted in the 
bracket nesting within x. Further, the delimiter 
characters comma, blank, semicolon, tab, and exclamation 
point become a part of x when they occur within the bracket 
nesting. 

5) If the leading character is a percent (%) character, then 
the sequence of characters that follows is taken as an 
expression that is evaluated immediately as a 16-bit value. 
The resulting value is converted to a decimal number and 
treated as an ASCII sequence of digits, with left zero 
suppression (0-65535). 

6) If the leading character is not a quote, a left bracket, or 
a percent, the possibly empty sequence of characters that 
follows, up to the next comma, blank, tab, semicolon, or 
exclamation point, becomes the value of x. 


Thece is one important exception to the preceding rules: the 
single-character escape, denoted by an up arrow, causes the macro 
assembler to read the special (nonalphabetic) character immediately 
following as a part of x without treating the character as 
significant. The character following the up arrow, however, must be 
a blank, tab, or visible ASCII character. The up arrow itself can 
be represented by two up arrows in succession. If the up arrow 
directly precedes a dummy parameter, then the up arrow is removed, 
and the dummy parameter is not replaced by its actual parameter 
value. Thus, the up arrow can be used to prevent evaluation of 
dummy parameters within the macro body. Note that the up arrow has 
no special significance within string quotes and is simply included 
as a part of the string. 

Evaluation of dummy parameters in macro expansions has been 
presented throughout the previous sections. The macro assembler 
evaluates dummy parameters as follows: 


•If a dummy parameter is either preceded or followed by the 
concatenation operator &, then the preceding or following & 
operator is removed, the actual parameter is substituted for 
the dummy parameter, and the implied delimiter is removed at 
the position where the ampersand occurs. 

• Dummy parameters are replaced only once at each occurrence as 
the encompassing macro expands. This prevents the infinite 
substitution that occurs if a dummy parameter evaluates to 
itself. 
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In summary, parameter evaluation follows these rules: 

• Leading and trailing tabs and blanks are removed. 

• Quoted strings are passed with their string quotes intact. 

• Nested brackets enclose arbitrary characters with delimiters. 

• A leading percent symbol causes immediate numeric evaluation. 

• An up arrow passes a special character as a literal value. 

• An up arrow prevents evaluation of a dummy parameter. 

• The & operator is removed next to a dummy parameter. 

• Dummy parameters are replaced only once at each occurrence. 


Listings 3-7, 8-8, and 8-9 show examples of macro definitions 
and invocations illustrating these points. In Listing 8-7, for 
example, two macros are defined, called MAC1 and MAC2. Each has 
several dummy parameters. In this case, the macro definitions are 
headed by D3 statements to reveal the actual values passed in each 
case. There is a single mainline invocation of MAC2 with the actual 
parameters 

I ,, X+l, % X + 1, 'kwote' 

that associates I with E, the null sequence with F, the sequence X+l 
with G, the value 16 with H, and the literal string 'kwote' with S. 
MAC 2 expands, filling the D3 and MV I instructions with the 
substituted values. Before leaving MAC2, MACl is invoked with the 
value of E (the sequence I) , the concatenation of the dummy argument 
F with the sequence M (producing M since F's value is null), along 
with the literal value A, followed by the value of H (which is 16), 
and terminated by the value of S (yielding the string 'kwote'). 
These values are associated with MACl's dummy parameters. 
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; MACRO PARAMETER EVALUATION 

i 

MACl MACRO A,8,C,D,S 

/ 

; ENTERING MACRO 1: 

OB ' &A &B &C &D' 

DB S 

A: NOP 

MVI B,1 

C&l: NOP 

L&A&D: NOP 

; LEAVING MACRO 1 

ENDM 

MAC2 MACRO E,F,G,H,S 

; ENTERING MACRO 2: 

DB ' &E &F &G &H' 

DB S 

MVI M,H 

MACl E,F&M,A,H,S 
LEAVING MACRO 2 


000F = X 


0000+492020582B 
0009+6B776F7465 
000E+3610 
+ 


0010+49204D2049 

0018+6B776F7465 

OOlD+OO I: 

001E+3601 

0020+00 II: 

0021+00 LI16: 


+ 


+ 

0022 


ENDM 

EQU 15 

MAC2 I ,, X+l, % X + 1, 'kwote' 

ENTERING MACRO 2: 

DB 'I X+l 16' 

DB 'kwote' 

MVI M,16 

MACl I,M,I,16,'kwote' 

ENTERING MACRO 1: 

DB 'I M I 16' 

DB 'kwote' 

NOP 

MVI M,1 

NOP 

NOP 

LEAVING MACRO 1 
ENDM 

LEAVING MACRO 2 

ENDM 

END 


Listing 8-7. Macro Parameter Evaluation Example 
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Upon expanding MAC1, the DB statements are filled out, followed by 
the substitution of A as a label (producing A's value I). The MVI 
instruction references memory because B's value is M. Note that the 
concatenation of C with 1 reduces to a concatenation of A with 1 
because C's value is A. The replacement of C by A constitutes a 
substitution of a single occurrence of a dummy parameter. Thus the 
A that is produced is not itself replaced at this point. Finally, 
the literal value L is concatenated to the value of A and D to 
produce the label LI16. 

Listing 8-8 illustrates the use of bracketed notation, using 
IRPs (indefinite repeats) within three macros, called IRPM1, IRPM2, 
and IRPM3. Note that one bracket level is removed in the first 
invocation of IRPM1, leaving the IRP list with one bracket level 
(required in the IRP heading). Similarly, the IRPM2 invocation also 
eliminates the outer bracket level, but these brackets are replaced 
at the IRP heading within IRPM2. IRPM3 has three distinct dummy 
parameters that are reconstructed as a single list at the IRP 
heading it contains. IRPM4 shows the effect of passing parameters 
through two macro invocation levels by accepting a single parameter 
X, which is immediately passed along to the IRPM1 macro. Note that 
the invocation requires three bracket levels: the first is removed 
at the nested invocation of IRPM1 inside IRPM4, and the innermost 
level is required at the IRP heading within IRPM1. 

Listing 8-9 presents various combinations of bracketed actual 
parameters, quoted strings, and escape sequences. The MAC1 macro 
has two parts: the first portion includes a DB statement showing 
the value of the first parameter X, if it is not empty, and the 
second part produces the value of Y, if not empty. Note that the 
first invocation includes a properly nested bracketed sequence for X 
and an empty parameter for Y. The second invocation sends a 
properly nested bracketed expression for X that produces an empty 
value because no characters remain after the brackets are removed. 
The second parameter includes a quoted string ('string of pearls') 
and a hexidecimal value that becomes a part of the DB in MAC1. 

The third invocation of MAC1 passes a bracketed expression, 
including a quoted string (the pair of adjacent apostrophes), 
followed immediately by a sequence of ASCII characters. Note that 
the pair of apostrophes are passed intact because they appear as an 
empty quoted string. In this case, the value of Y is empty. The 
remaining examples show various cases of strings and escape 
sequences. Take care in passing quoted strings that contain 
apostrophes because a pair of apostrophes is considered a single 
apostrophe at each evaluation level in the sequence of macro 
invocations. Pay particular attention to the use of the escape 
character to pass an unevaluated dummy parameter from MAC2 to the 
MAC1 invocation. 
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IRPMl 

MACRO 

X 


7 7 

INDEFINITE REPEAT MACRO 



IRP 

Y,X 


Y: 

NOP 




ENDM 




ENDM 



7 

IRPMl 

< <ONE,TWO,THREE > > 

0000+00 

ONE: 

NOP 


0001+00 

TWO: 

NOP 


0002+00 

THREE: 

NOP 



IRPM2 

MACRO 

X 



IRP 

Y, <X> 


Y: 

NOP 




ENDM 




ENDM 



7 

IRPM2 

<FOUR,FIVE,SIX> 

0003+00 

FOUR: 

NOP 


0004+00 

FIVE: 

NOP 


0005+00 

SIX: 

NOP 



IRPM3 

MACRO 

X1,X2,X3 



IRP 

Y,<X1,X2,X3> 


Y: 

NOP 




ENDM 




ENDM 



7 

IRPM3 

SEVEN,EIGHT,NINE 

0006+00 

SEVEN: 

NOP 


0007+00 

EIGHT: 

NOP 


0008+00 

NINE: 

NOP 



IRPM4 

MACRO 

X 



IRPMl 

X 



ENDM 



7 

IRPM4 

< < <TEN,ELEVEN,TWELVE> 

0009+00 

TEN: 

NOP 


000A+00 

ELEVEN: 

NOP 


000B+00 

TWELVE: 

NOP 


oooc 


END 



Listing 8-8. Parameter Evaluation Using Bracketed Notation 
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SAMPLE BRACKETED PARAMETERS, WITH ESCAPE CHARACTER 


MAC1 

MACRO 

DB 

IF 

EXITM 

ENDIF 

DB 

ENDM 

7 

MAC1 

0000+3C4C454654 

DB 

7 

MAC1 

001F+737472696E 

DB 

7 

MAC1 

0030+412051554F 

DB 

7 

MAC1 

0046+7269676874 

DB 

7 

MAC1 

0057+6973207468 

DB 

7 

MAC1 

006B+4845524520 

DB 

MAC 2 

MACRO 

LOCAL 

X 

EQU 

DB 

MAC1 

ENDM 

7 

MAC 2 

000A+= ?? 0001 

EQU 

007E+3C 

DB 

007F+41504152 

DB 

0083+7768617427 

DB 


X Y 

'&X' ;(ONE) 

NUL Y 


Y ?(TWO) 


<<LEFT SIDE> MIDDLE <RIGHT SIDE>> 

’<LEFT SIDE> MIDDLE <RIGHT SIDE>' 

<>,<’string of pearls’,34H> 

'string of pearls’,34H ;(TWO) 

<A QUOTE IS A '', RIGHT?> 

’A QUOTE IS A ", RIGHT?' ;(ONE) 

<>,<’right, but also ''"'> 

'right, but also "' ; (TWO) 

,<’is this ',"''' confusing' ’ ' ' ' , 63> 
'is this confusing'", 63 ; (TWO) 

<HERE IS A "> AND A 

'HERE IS A > AND A A ' ;(ONE) 

APAR,BPAR 

X 

10 

APAR 

~APAR,BPAR 


(X+5)*4,'what'''''"'s going on?' 
10 

(??0001+5)*4 
'APAR' ?(ONE) 

'whaf's going on?' ; (TWO) 


;(ONE) 


Listing 8-9. Examples of Macro Parameter Evaluation 


Examine the various parameters and their evaluations in Listing 
8-9 to ensure that the rules for evaluation given in this section 
are consistent. 
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8.8 The MACLIB Statement 

The macro assembler allows you to create and reference macro 
library files that are external to the mainline program. The form 
of the macro library reference is 

MACLIB libname 

where libname is an identifier referencing file libname.LIB assumed 
to exist on the disk. Macro libraries are in source program form, 
so you can easily create and modify them using an editor program. 

In order to speed up the assembly process, macro libraries are 
read only on the first assembly pass. This places some restrictions 
on the use of the MACLIB statement, as listed below: 


• The statements included in the macro library cannot generate 
machine code. For example, comments, EQUs, SETs, and MACRO 
definitions are allowed; DB statements outside macro 
definitions are not allowed. 

• Macro libraries are not listed with the source program, 
although an overriding parameter can be supplied. (See Section 


• All MACLIB statements must appear before the mainline program 
macro definitions. The MACLIB statements are placed at the 
beginning of the program, followed by the mainline" declarations 
and machine code. 


The principal advantage of the MACLIB feature is that you can 
predefine macros that enhance the facilities of the assembly 
language itself. For example, the additional operations codes of 
the Zilog Z80 microprocessor can be defined in a macro library that 
is referenced in a single statement 

MACLIB Z80 

causing the assembler to read the file Z80.LIB from the disk that 
contains the necessary macros for Z80 code generation. These macros 
can then be referenced within the program, intermixed with the usual 
8080 mnemonics. 

The libname.LIB file is assumed to exist on the currently 
logged disk drive. You can override this default condition using a 
special parameter (L) when the macro assembler is started that 
-4- ec ts the .LIB references to a different disk. (See Section 
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Listings 6-1 and 6-2 show the use of the macro library 
facility, as introduced in the initial macro discussion. The 
following sections contain additional examples of the use of MACLIB 
in practical applications. 


End of Section 8 
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The MAC assembler provides a powerful tool for microcomputer 
systems development through its macro facilities. To demonstrate 
this, the following sections describe a number of macro applications 
that solve practical problems in four applications areas: 

• implementation of special purpose languages 

• emulation of nonstandard machine architectures 

• implementation of additional control structures 

• operating systems interface macros 


9.1 Special Purpose Languages 

A wide variety of microcomputer designs can be broadly classed 
as controller applications. Specifically, the microcomputer is used 
as the controlling element in sequencing and decision making as 
real-time events are sampled and directed. 

Typical applications of this sort include assembly line sensing 
and control, metal machine control, data communications and terminal 
control functions, production instrumentation and testing, and 
traffic control systems. 

In many cases, application programmers set up the sequence of 
operations that the microprocessor carries out in performing its 
task. To avoid unnecessary details, the application programmer is 
not expected to know how to program and debug microcomputer assembly 
language programs. 

In this situation, it is useful to define a language through 
macros that suit the application. The application programmer uses 
these predefined macros as the primitive language elements. If 
properly defined, the application language is easily programmed, 
allowing considerable machine independence. That is, an application 
program written for a particular microprocessor can be used with 
another processor by changing the definitions of the individual 
macros that implement the primitive operations. Further, the macro 
bodies can incorporate debugging facilities for application 
development. 

To illustrate language definition, consider the following 
situation. Hornblower Highway Systems, Inc. produces turnkey 
traffic control systems for cities throughout the country. Their 
hardware subsystems consist of various traffic lights and sensors 
customized for the traffic layout in a particular city. When 
Hornblower negotiates a contract, their engineers survey the 
intersections of the city and produce plans showing a configuration 
of their standard hardware for each intersection, along with the 
algorithms required for traffic flow at that point. 
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The standard hardware items Hornblower manufactures consist of 
central and corner traffic lights that display green, yellow, and 
red (or off completely); pushbutton switches for pedestrian cross 
requests; road treadles for sensing the presence of an automobile at 
an intersection; and a central controller box. 

The central controller box contains an 8080 microcomputer 
connected through external logic to relays that control the lights 
and latches that hold the sensor input information. The controller 
box also contains a time of day clock that changes on an hourly 
basis from 0 through 23. The 8080 processor in the controller box 
can be configured for any particular intersection with up to 1024 
bytes of programmable Read-Only Memory (PROM) in 256-byte 
increments. Although Random Access Memory can be included in the 
controller box, Hornblower uses only ROM when possible. 

Thus, the Hornblower engineers examine the hardware 
requirements for each intersection in the city and produce hardware 
configuration plans that intermix the various standard components. 
Programs are then written and debugged that control each 
intersection, based on predicted traffic patterns. 

The intersection of Easy Street and Maria Avenue, for example, 
controls minimal traffic and thus consists of a controller box with 
a single central light. The algorithm for this intersection simply 
alternates red and green lights between Easy and Maria, with a bias 
toward Easy Street because traffic along Easy has measured higher in 
the past surveys. Thus the green light along Easy lasts for 20 
seconds, while the green along Maria lasts for only 15 seconds. 
Given this situation, the application programmer writes the 
following program: 


HORNBLOWER HIGHWAYS SYSTEMS, INC. 
INTERSECTION: 

EASY STREET (N-S) / MARIA AVENUE(E-W) 


MACLIB 

INTERSECT 

; LOAD 

MACROS 

SETLITE 

NS,GREEN 



SETLITE 

EW, RED 



TIMER 

20 

;WAIT 

20 SECS 

CHANGE : 

LIGHTS 



SETLITE 

NS,YELLOW 



TIMER 

3 

; WAIT 

3 SECS 

SETLITE 

NS,RED 



SETLITE 

EW,GREEN 



TIMER 

15 

; WAIT 

15 SECS 

CHANGE BACK 



SETLITE 

EW,YELLOW 



TIMER 

3 

; WAIT 

3 SECS 

RETRY 

CYCLE 
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The macro library INTERSECT.LIB contains the macro definitions that 
implement the primitive operations SETLITE and TIMER, setting the 
central traffic light and time out for the specified interval, 
respectively. Further, the RETRY macro causes the traffic light to 
recycle on each light change. The sequence of operations is easy to 
write and is completely machine independent. 

Listing 9-1 gives an example of a macro library for intersect 
that assumes the following hardware with an 8080 processor: the 
central traffic light is controlled by the 8080 output port 0 (given 
by light) ; the time of day clock is read from port 3 (clock) . 
Further, the north-south (nsbits) of the central light are given by 
the high-order 4 bits of output port 0? the east-west direction 
(ewbits) is specified in the low-order 4 bits of output port 0. 
When either of these fields is set to 0, 1, 2, or 3, the light in 
that direction is turned off, or set to red, yellow, or green, 
respectively. Thus, the SETLITE macro in Listing 9-1 accepts a 
direction (NS or EW) along with a color (OFF, RED, YELLOW, or GREEN) 
and sets the specified direction to the appropriate color. 
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macro library for basic intersection 

input/output ports for light and clock 
light equ OOh ;traffic light control 

clock equ 03h ;24 hour clock ( 0 , 1 ,..., 23) 


nsbits 

ewbits 


constants for traffic light control 


equ 4 ;north south bits 

equ 0 ?east west bits 

off equ 0 ;turn light off 

red equ 1 ;value for red light 

yellow equ 2 ;value for yellow light 

green equ 3 ;green light 

} 

setlite macro dir,color 

;; set light "dir" (ns,ew) to "color" (off,red,yellow,green) 

mvi a,color shl dir&bits ;?color readied 

out light ;;sent in proper bit position 

endm 


timer 


tls 
t 2 : 
t3: 


macro seconds 
construct inline time-out loop 


local 

mvi 

mvi 

mvi 

dcr 

jnz 

dcr 


tl,t2,t3 
d,4*seconds 


;;loop entries 
;;basic loop control 


b, 250 ;;250msec *4=1 sec 

c, 182 ;;182*5.5usec = 1 msec 

c ;?1 cy = .5 usee 

t3 ;?+10 cy = 5.5 usee 

b ;;count 250,249... 

t 2 ;;loop on b register 

d ;;basic loop control 

tl ;;loop on d register 

arrive here with approximately "seconds" secs timeout 
endm 


jnz 

dcr 

jnz 


clock? macro low,high,iftrue 


iffalse: 


jump to 

local 

in 

if 

cpi 

jnc 

endif 

cpi 

jnc 

endm 


"iftrue" if clock is between low and high 
iffalse ?;alternate to true case 
clock ?;read real-time clock 
not nul high ;?check high clock 
high ?;equal or greater? 
iffalse ? 7 skip to end if so 

low 77 less than low value? 

iftrue 77 skip to label if not 


retry macro golabel 

77 continue execution at "golabel" 

jmp golabel 
endm 


Listing 9-1. Macro Library for Basic Intersection 
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The TIMER macro in Listing 9-1 uses the internal cycle time of 
the 8080 processor to construct an inline timing loop, based on the 
value of SECONDS. This loop is not generated as a subroutine 
because Hornblower prefers not to include RAM in the controller box. 
(Subroutines require return addresses in RAM.) 

In addition to the basic intersection macro library, Hornblower 
has also defined macro libraries for all of the optional hardware 
components. Listing 9-2a, for example, is included when the 
intersection contains treadles in the street to detect automobiles; 
Listing 9-2b shows the macro library for pedestrian pushbuttons. In 
the case of automotive treadles, the sensors are attached to input 
port 1 (trinp) of the processor. The treadles, however, require a 
reset operation that clears the latched value through output port 1 
(trout) of the controlling 8080 processor. In any particular 
intersection, the treadles are numbered clockwise from true north, 
labeled 0, 1, through a maximum of 7 treadles. Each sensor and 
reset position of the treadle ports corresponds to one bit position, 
numbered from the least to most significant bit. Thus the treadle 
#0 sensor is read from bit 0 of port 1 and reset by setting bit 0 of 
output port 1. Similarly, treadle #1 uses bit position 1 of input 
and output port 1. The TREAD? macro is invoked to sense the 
presence of a latched value for treadle tr and, if on, the sensor is 
reset, with control transferring to the label given by iftrue. 

Listing 9-2b shows the macro library that processes pedestrian 
pushbuttons. Hornblower*s hardware senses the latched pedestrian 
switches on input port 0 (cwinp) as a sequence of Is and 0s in the 
least significant positions, corresponding to the switches at the 
intersection. Thus, if there are four pedestrian switches, bit 
positions 0, 1, 2, and 3 correspond to these switches. A 1 bit in 
any of these positions indicates that the pushbutton has been 
depressed. Unlike the automotive treadles, the crosswalk switch 
latches are all cleared whenever input port 0 is read. Hornblower 
has defined several other libraries that support optional hardware 
manufactured by their company. 
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; macro library for street treadles 

7 

trinp equ Olh ;treadle input port 

trout equ Olh 7 treadle output port 

7 

tread? macro tr,iftrue 

77 "tread?" is invoked to check if 

;; treadle given by tr has been sensed. 

77 if so, the latch is cleared and control 

;; transfers to the label "iftrue" 

local iffalse ??in case not set 


in 

ani 

jz 

mvi 

out 

jmp 

iffalse: 

endm 


trinp ?? 
1 shl tr 
iffalse 
a,l shl tr 
trut 
iftrue 


read treadle switches 

;;mask proper bit 
;?skip reset if 0 
;;to reset the bit 
7 ?clear it 
??go to true label 


Listing 9-2a. Macro Library for Treadle Control 


7 macro library for pedestrian pushbuttons 

7 

cwinp equ OOh ?input port for crosswalk 

7 

push? macro iftrue 

77 "push?" jumps to label "iftrue" when any one 

77 of the crosswalk switches is depressed. The 

7 ? value has been latched, and reading the port 

7 ? clears the latched values 


in 

cwinp 

? ? read 

the crosswalk switches 

ani 

(1 shl 

cwcnt) 

- 1 77 build mask 

jnz 

iftrue 

7 7 any 

switches set? 


continue on false condition 
endm 

Listing 9-2b. Macro Library for Corner Pushbuttons 


The intersection of Bumpenram Boulevard and Lullabye Lane 
presents a more complicated situation. Bumpenram carries heavy 
traffic in an E-W direction to and from the center of town. 
Lullabye, however, feeds a residential portion of the city, running 
perpendicular to Bumpenram in a N-S direction. The contracting city 
wants the traffic control biased toward Bumpenram as follows: the 
traffic light must remain green along Bumpenram until the treadles 
along Lullabye detect the presence of automobiles or until the 
pedestrian switches are pushed. At that time, the light must change 
to allow the traffic to move N-S through Lullabye, allowing all 
traffic to clear before returning to the major E-W flow along 
Bumpenram. Late night traffic along Bumpenram is not very heavy, so 
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the city also wants the E-W light to flash yellow and the N-S 
direction to flash red between the hours of 2 and 5 a.m. 

The application program created by Hornblower for the Bumpenram 
and Lullabye intersection is shown in Listings 9-3a, 9-3b, and 9-3c. 
Each major cycle of the traffic light enters at CYCLE where the time 
of day is tested. Between 2 and 5 a.m., control transfers to NIGHT 
where the yellow and red lights are flashed in the appropriate 
directions. During other hours, the switches and treadles are 
sampled until N-S traffic along Lullabye is sensed. If cross 
traffic is detected, the lights switch until all the traffic is 
through. Sampling also stops when the time of day reaches 2 a.m. 

Listing 9-3a shows the assembly with no macro generated lines, 
controlled by the -M parameter. (See Section 10.) Although the 
machine code locations are shown to the left, no 8080 machine code 
is listed. Listing 9-3b shows a segment of this same program with 
machine code generation, but no 8080 mnemonics, controlled by *M. 
Listing 9-3a is the most readable to the application programmer. 
Listings 9-3b and 9-3c are useful for macro debugging. 

Note that the resulting program requires no RAM for execution 
because all temporary values are maintained in the 8080 registers. 
Further, the program is less than 256 bytes, so it can be placed in 
a single programmable Read-Only memory chip for a minimum 
memory/processor configuration. 


All Information Presented Here is Proprietary to Digital Research 


89 





Programmer's Utilities Guide 


9.1 Special Purpose Languages 


0004 

0000 

0001 


INTERSECTION: BUMPENRAM BLVD / LULLABYE LN. 


CWCNT EQU 4 
LULLO EQU 0 
LULL1 EQU 1 


;SET TO 4 CROSSWALK SWITCHES 
;NAME FOR TREADLE ZERO 
;NAME FOR TREADLE ONE 


MACLIB INTER ;BASIC INTERSECTION 

MACLIB TREADLES ;INCLUDE TREADLES 

MACLIB BUTTONS ;INCLUDE PUSHBUTTONS 


0000 

000C 

0010 


CYCLE: ;ENTER HERE ON EACH MAJOR CYCLE OF THE LIGHT 

CLOCK? 2,5,NIGHT ?SPECIAL FLASHING? 

;NOT BETWEEN 2 AND 5 AM 

SETLITE NS,RED ;RED LIGHT ON LULLABYE 

SETLITE EW,GREEN ;GREEN ON BUMPENRAM 


0014 
00 IB 
0029 
0037 
003E 


SAMPLE: ;SAMPLE 
PUSH? 
TREAD? 
TREAD? 
CLOCK? 
RETRY 


THE BUTTONS AND 
SWITCH ;ANYONE 
LULLO,SWITCH 
LULL1,SWITCH 
2,,NIGHT 
SAMPLE 


TREADLES 

THERE? 

;TREADLE 0? 

;TREADLE 1? 

;PAST 2AM? 

;TRY AGAIN IF NOT 


0041 

0045 

0057 

005B 

005F 


SWITCH: 

;SOMEONE IS WAITING, 
SETLITE EW,YELLOW 
TIMER 3 
SETLITE EW,RED 
SETLITE NS,GREEN 
TIMER 23 


CHANGE LIGHTS 

;SLOW 'EM DOWN 
;WAIT 3 SECONDS 
;STOP 'EM 
;LET 'EM GO 
;FOR AWHILE 


DONE?: ?IS ALL THE TRAFFIC THROUGH ON LULLABYE? 

0071 TREAD? LULLO,NOTDONE ;TREADLE 0? 

007F TREAD? LULLl,NOTDONE ;TREADLE 1? 

;NEITHER TREADLE IS SET, CYCLE 

008D RETRY CYCLE ;FOR ANOTHER LOOP 


NOTDONE: 


0090 


TIMER 

5 

;WAIT 5 SECONDS 

00A2 


RETRY 

DONE? 

;TRY AGAIN 


NIGHT: 

;THIS IS NIGHTTIME, FLASH LIGHTS 

00A5 


SETLITE 

EW,OFF 

;TURN OFF 

00A9 


SETLITE 

NS,OFF 

7 TURN OFF 

00 AD 


TIMER 

1 

;WAIT WITH OFF 

00BF 


SETLITE 

EW,YELLOW 

?TURN TO YELLOW 

00C3 


SETLITE 

NS,RED 

;TURN TO RED 

00C7 


TIMER 

1 

;LEAVE ON FOR 1 SEC 

00D9 


RETRY 

CYCLE 

?GO AROUND AGAIN 


Listing 9-3a. 

Traffic 

Control Algorithm using -M Option 
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INTERSECTION: BUMPENRAM BLVD / LULLABYE LN. 


0004 = 

CWCNT 

EQU 

4 

? SET TO 4 CROSSWALK SWITCHES 

0000 = 

LULLO 

EQU 

0 

;NAME FOR TREADLE ZERO 

0001 = 

LULLl 

EQU 

1 

;NAME FOR TREADLE ONE 


MACLIB 

INTER 


;BASIC INTERSECTION 


MACLIB 

TREADLES 


?INCLUDE TREADLES 


MACLIB 

BUTTONS 


;INCLUDE PUSHBUTTONS 


CYCLE: 

;ENTER HERE ON 

EACH MAJOR CYCLE OF THE LIGHT 


CLOCK? 2,5 ,NIGHT ;SPECIAL FLASHING? 

0000+DB03 

0002+FE05 

0004+D20C00 

0007+FE02 

0009+D2A500 

;NOT BETWEEN 2 AND 5 AM 

SETLITE NS,RED ;RED LIGHT ON LULLABYE 

000C+3E10 

000E+D300 

SETLITE EW,GREEN ;GREEN ON BUMPENRAM 

0010+3E03 

0012+D300 


0014+DB00 

0016+E60F 

0018+C24100 

001B+DB01 

001D+E601 

001F+CA2900 

0022+3E01 

0024+D301 

0026+C34100 

0029+DB01 

002B+E602 

002D+CA3700 

0030+3E02 

0032+D301 

0034+C34100 

0037+DB03 

0039+FE02 

003B+D2A500 

003E+C31400 


SAMPLE: ;SAMPLE THE BUTTONS AND TREADLES 
PUSH? SWITCH ?ANYONE THERE? 


TREAD? LULLO,SWITCH ;TREADLE 0? 


TREAD? LULL1,SWITCH ;TREADLE 1? 


CLOCK? 2,,NIGHT ;PAST 2 AM? 


RETRY SAMPLE ;TRY AGAIN IF NOT 


Listing 9-3b. Intersection Algorithm with *M in Effect 
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SWITCH• 

;SOMEONE IS WAITING, CHANGE LIGHTS 



SETLITE 

EW,YELLOW 

;SLOW 'EM DOWN 

0041+3E02 

MV I 

A,YELLOW SHL EWBITS 

0043+D300 

OUT 

LIGHT 



TIMER 

3 

;WAIT 3 SECONDS 

0045+160C 

MV I 

D f 4*3 


0047+06FA 

??0005: MVI 

B, 250 


0049+0EB6 

??0006: MVI 

C, 182 


004B+0D 

??0007: DCR 

C 


004C+C24B00 

JNZ 

?? 0007 


004F+05 

DCR 

B 


0050+C24900 

JNZ 

?? 0006 


0053+15 

DCR 

D 


0054+C24700 

JNZ 

?? 0005 



SETLITE 

EW r RED 

;STOP 'EM 

0057+3E01 

MVI 

A,RED SHL EWBITS 


0059+D300 

OUT 

LIGHT 



SETLITE 

NS,GREEN 

;LET 'EM GO 

005B+3E30 

MVI 

A,GREEN SHL NSBITS 

005D+D300 

OUT 

LIGHT 



TIMER 

23 

;FOR AWHILE 

005F+165C 

MVI 

D,4* 23 


0061+06FA 

??0008: MVI 

B j 250 


0063+03B6 

??0009: MVI 

C f 182 


0065+0D 

770010: DCR 

C 


0066+C26500 

JNZ 

??0010 


0069+05 

DCR 

B 


006A+C26300 

JNZ 

?? 0009 


006D+15 

DCR 

D 


006E+C26100 

JNZ 

?? 0008 



DONE?: ;IS ALL 

THE TRAFFIC THROUGH ON LULLABYE? 


TREAD? 

LULL0,NOTDONE 

;TREADLE 0? 

0071+DB01 

IN 

TRINP 


0073+E601 

AN I 

1 SHL LULL0 


0075+CA7F00 

JZ 

??0011 


0078+D301 

MVI 

A,1 SHL LULL0 


007A+D301 

OUT 

TROUT 


007C+C39000 

JMP 

NOTDONE 



TREAD? 

LULLl,NOTDONE 

;TREADLE 1? 

007F+DB01 

IN 

TRINP 


0081+E602 

AN I 

1 SHL LULLl 


0083+CA8D00 

JZ 

??0012 


0086+3E02 

MVI 

A,1 SHL LULLl 


0088+D301 

OUT 

TROUT 


008A+C39000 

JMP 

NOTDONE 



;NEITHER TREADLE IS SET, 

, CYCLE 


RETRY 

CYCLE 

;FOR ANOTHER LOOP 

008D+C30000 

JMP 

CYCLE 



Listing 9-3c. Algorithm with Generated Instructions 
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Macro-based languages of this sort can easily incorporate 
debugging facilities. In the case of Hornblower, Inc., the 
principal algorithms are constructed and tested in the CP/M 
environment by including debugging traces within each macro. In 
each case, a debug flag is tested and, if true, machine code is 
generated to trace the operation at the console, rather than 
actually executing the input/output calls. 

Listing 9-4 shows the modification required to the INTER.LIB 
file to include the debugging code. Although only the SETLITE macro 
is shown, similar coding is easily included for the remaining 
macros. Listing 9-4 includes the debug flag at the beginning of the 
library, initially set to FALSE, along with the appropriate equates 
for CP/M system calls. If the debug flag is set to true by the 
application programmer, special trace calls are included. For 
example, the setlite macro constructs a message of the form 

DIR changing to COLOR 

where DIR and COLOR are the parameters sent to the macro. If debug 
remains false in the application program, this trace code is not 
assembled. 


All Information Presented Here is Proprietary to Digital Research 


93 




Programmer's Utilities Guide 


9.1 Special Purpose Languages 



macro 

library 

for basic intersection 


global 

definitions for debug processing 

true 

equ 

Offffh 

;value of true 

false 

equ 

not true;value of false 

debug 

set 

false 

;initially false 

bdos 

equ 

5 

;entry to cp/m bdos 

rchar 

equ 

1 

?read character function 

wbuf f 

equ 

9 

;write buffer function 

cr 

equ 

Odh 

;carriage return 

If 

equ 

Oah 

;line feed 

i 

input/output ports for light and clock 

light 

equ 

OOh 

;traffic light control 

clock 

equ 

03h 

;24 hour clock (0,1,..., 

r 

bit positions 

for traffic light control 

nsbits 

equ 

4 

;north south bits 

ewbits 

equ 

0 

;east west bits 


off 

red 

yellow 

green 


constant values 
equ 0 

equ 1 

equ 2 

equ 3 


for the light control 
;turn light off 
;value for red light 
;value for yellow light 
;green light 


setlite macr dir,color 

.. set light given by "dir" to color given by "color" 

if debug ??print info at console 

local setmsg,pastmsg 

mvi c,wbuff ;;write buffer function 

lxi d,setmsg 

call bdos ;;write the trace info 

jmp pastmsg 

setmsg: db cr,lf 

db '&DIR changing to &COLOR$' 


pastmsg: 

exitm 

endif 

mvi 

out 

endm 


a,color shl dir&bits ;;readied 
light ;;sent in proper bit position 


(remaining macros are identical to the previous figure, 
but each contains trace information similar to "setlite") 


Listing 9-4. Library Segment with Debug Facility 
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Listing 9-5a shows an application program for an intersection 
where the debug flag is set to TRUE after the macro library is 
included. As a result, each macro expansion assembles a call to the 
CP/Moperating system to trace the light direction and color change, 
skipping the machine code that is eventually assembled to drive the 
actual Hornblower hardware. 


The application programmer then uses CP/M to trace the 
operation of the algorithm, resulting in the printout shown in 
Listing 9-5b. Each trace line corresponds to a SETLITE call with a 
specific direction and color, with the appropriate wait time between 
printouts. 


0100 


ORG 

MACLIB 

FFFF # 

DEBUG 

SET 

0100 

CYCLE: 

SETLITE 

0120 


SETLITE 

0142 


TIMER 

0154 


SETLITE 

0177 


TIMER 

1089 


SETLITE 

01A9 


SETLITE 

01CB 


TIMER 

01DD 


SETLITE 

0200 


TIMER 

0212 


RETRY 


10OH ;READY FOR THE DEBUG RUN 

INTER ;BASIC MACRO LIBRARY 

TRUE ;READY DEBUG TOGGLE 

NS,RED 
EW,GREEN 
10 

EW,YELLOW 
2 

EW,RED 
NS,GREEN 
10 

NS,YELLOW 
2 

CYCLE 


Listing 9-5a. Sample Intersection Program with Debug 


NS changing to RED 
EW changing to GREEN 
EW changing to YELLOW 
EW changing to RED 
NS changing to GREEN 
NS changing to YELLOW 
NS changing to RED 
EW changing to GREEN 
EW changing to YELLOW 
EW changing to RED 


Listing 9-5b. Debug Trace Printout 
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Upon completion of the initial debugging under CP/M, the SET 
statement in the application program is removed—the ORG can be 
removed as well—and the program is reassembled. This time, the 
CP/M traces are not included because the debug flag remains FALSE. 
As a result, the actual Hornblower hardware interface is assembled 
instead. The newly assembled program is then placed into PROM in 
the controller box for that intersection and tested in its target 
environment. 

This approach to macro based language facilities provides a 
simple tool for rapid development and debugging of programs where 
high-level languages are not available, but a measure of machine 
independence is required. The macros are easy to develop, and the 
application programs are simple to write and debug. 


9.2 Machine Emulation 

A second application of macro processing is in the emulation of 
a machine operation code set that is different from the 8080 
microprocessor. In particular, a machine architecture is selected, 
based on an existing or fictitious operation code set, and a macro 
is written for each opcode, taking the general form: 

op MACRO d 1,d-2,. . .,d— n 
opcode emulation 
ENDM 

where op is a mnemonic instruction in the emulated machine, and the 
dummy parameters d-1 through d-n represent the optional operands 
required by op. The macro body includes 8080 instructions that 
carry out the operation on the 8080 microprocessor. This means the 
instructions within the macro body perform the same function as the 
op with its arguments on the emulated machine. 

Upon completion of the opcode macro definitions, a program can 
be written using these opcodes. These opcodes expand to the 
equivalent 8080 instructions but perform the emulated machine 
operations. 

For example, consider the situation encountered by Nachtflieger 
Masch i newe r ke , an internationally famous manufacturer and 
distributor of automated machining equipment. Though incorporating 
microprocessors in controlling their equipment, Nachtflieger expects 
to build a custom LSI processor for their future products. The 
processor, called the KDF-10, will be used primarily as an analog 
sensing and control element in a larger electronic environment. As 
a result, the KDF-10 word size must accommodate digital values 
corresponding to analog signals of up to 12 bits. To allow 
computations on these 12-bit values, Nachtflieger engineers are 
going to allow a full 16-bit word in the KDF-10, along with a number 
of primitive operations on these values. Externally, the KDF-10 
will provide four analog-to-digital input ports (A-D) that can be 
read by KDF-10 programs, along with four digital-to-analog output 
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ports (D-A) that can be written by the program. The KDF-10 will 
automatically perform the A-D and D-A conversion at these ports. 

, • Be ^ n ^ forward thinkers, the engineers at Nachtflieger have 

esigned the KDF-10 as a stack machine, similar in concept to the 
Pa i :k ^ ar * d HP u~ 65 handheld programmable calculator, where data 

DusMna »vfd- ? top , of 5 stack of dafc a elements, automatically 
pushing existing elements deeper onto the stack. Similar to the 
Reverse Polish Notation (rpn) of an HP-65, arithmetic on the KDF-10 
will b e performed on the topmost stacked elements, automatically 
absorbing the stacked operands as the arithmetic is performed. The 
° n the followin 9 three-character operation codes 

tor the KDF-10: 


SIZ n 

RDM i 

WRM o 

DUP 

SUM 


LSR n 


JMP a 


reserves n 16-bit elements as the maximum size of the 
KDF-10 operand stack. This operation code must be 
provided at the beginning of the program. 

reads the analog signal from input port i (0, 1. 2. 
or 3) to the top of the stack. 

writes the digital value from the top of the stack to 
the D-A output port given by o (0, 1, 2, or 3). The 
value at the stack top is removed. 

duplicates the top of the KDF-10 stack. 

adds the top two elements of the KDF-10 stack. Both 
operands are removed, and the resulting sum is 
placed on the top of the stack. 

performs a logical shift of the topmost stacked 
element to the right by n bits (1, 2, . . .,15), 
replacing the original operand by the shifted 
result. LSR n performs a division of the topmost 
stacked value by the divisor 2 to the n power. 

branches directly to the program address given by 
label a. 


Because the KDF-10 does not exist, except in the minds of the 
Nachtflieger engineers, the software designers decided to use the 
macro facilities of MAC to emulate the KDF-10, usinq the 8080 
microcomputer. y 


Listing 9-6 shows an example of a program for the KDF-10 that 
! a \^° CeSSed by MAC usin 9 the macro library defined by the 
Nachtflieger software group. In this situation, the KDF-10 is 
connected to four temperature sensors attached at strategic places 
on the machining equipment. The program continuously reads the four 
input values from the A-D ports and computes their average value by 
summing and dividing by four. This average value is sent to D-A 
output port 0 where it is used to set environmental controls. 
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. 

AVERAGE 

THE VALUES WHICH ARE READ FROM ANALOG 


. 

INPUT PORTS, WRITE THE RESULTING VALUE TO ALL 


7 

THE D-A 

OUTPUT 

PORTS. 


7 

MACLIB 

STACK 

•READ THE STACK MACHINE OPCODES 

0000 


SIZ 

20 

;CREATE 20 LEVEL WORKING STACK 

012E 

LOOP: 

RDM 

0 

;READ A-D PORT 0 

0134 


RDM 

1 

;READ A-D PORT 1 

0136 


RDM 

2 

?READ A-D PORT 2 

013A 


RDM 

3 

;READ A-D PORT 3 


9 

ALL FOUR VALUES ARE STACKED, ADD THEM UP 

013E 


SUM 


;AD3+AD2 

0140 


SUM 


; (AD3+AD2)+AD1 

0142 


SUM 


; ( (AD3+AD2)+ADl)+AD0 



SUM IS 

AT TOP 

OF THE STACK, DIVIDE BY 4 

0144 


LSR 

2 

;SHIFT RIGHT TWO = DIV BY 4 

0152 


WRM 

0 

;WRITE RESULT TO D-A PORT 0 

0156 C32E01 


JMP 

LOOP 

;GO GET ANOTHER SET OF VALUES 


Listing 9-6. A-D Averaging Program Using Stack Machine 


As shown in Listing 9-6 f the program begins by reserving a 
stack of 20 elements, a much larger stack than required for this 
application, since a maximum of four elements are actually stacked. 
The program then cycles following LOOP, where the values are read 
and processed. The four operations RDM 0, RDM 1, RDM 2, and RDM 3 
read all four temperature sensors, placing their data values in the 
stack. The three SUM operations that follow the read operations 
perform pairwise addition of the temperature values, producing a 
single sum at the top of the stack. Because the average value is 
wanted, the LSR 2 operator is applied to the stack top to perform 
the division by four. Finally, the resulting average is sent to the 
D-A port using the WRM 0 operation code. Control then transfers 
back to LOOP, where the entire operation is performed again. 

Because Nachtflieger designers are emulating KDF-lOs using 
8080s, they have created the macro library file, called STACK.LIB, 
as shown in Listing 9-7. A macro is shown in this listing for each 
of the KDF-10 opcodes, starting with the SIZ operator. In this 
case, the program origin is set, since this must be the first opcode 
in the program, and the stack area is reserved. Note that double 
words of storage are reserved because a 16-bit word size is assumed. 
The DUP, SUM, and LSR operators follow the SIZ macro. In each case, 
the KDF-10 stack top is assumed to be in 8080's HL register pair. 
Further, each operation that pushes the KDF-10 stack causes the 
element in the 8080 HL pair to be pushed to the 8080 memory area 
reserved by the SIZ opcode. 
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S1Z 

macro size 


7 7 

set "org" and 

create stack 


local 

stack 

;;label on the stack 


org 

lOOh 

;? at base of TPA 


lxi 

sp,stack 


jmp 

stack 

;;past stack 


ds 

size*2 

;;double precision 

stack: 

endm 



7 

dup 

macro 



7 7 

duplicate top 

of stack 


push 

h 



endm 



7 

sum 

macro 



7 7 

add the 

top two stack elements 


pop 

d 

;;top-1 to de 


dad 

d 

;? back to hi 


endm 



lsr 

macro 

len 


7 7 

logical 

shift 

right by len 


rept 

len 

??generate inline 


xra 

a 

;;clear carry 


mov 

a, h 



rar 


;;rotate with high 0 


mov 

h f a 



mov 

a, 1 



rar 




mov 

1/a 

;?back wi** K ^iah bit 


endm 




endm 



7 

adcO 

equ 

1080h 

;a-d converter 0 

add 

equ 

108 2h 

;a-d converter 1 

adc2 

equ 

1084h 

;a-d converter 2 

adc3 

equ 

1086h 

;a-d converter 3 

7 

dacO 

equ 

1090h 

?d-a converter 0 

dacl 

equ 

1092h 

;d-a converter 1 

dac2 

equ 

1094h 

;d-a converter 2 

dac3 

equ 

1096h 

;d-a converter 3 

7 

rdm 

macro 

? c 


7 7 

read a-d converter number "?c" 


push 

h 

?;clear the stack 

7 

read from memory mapped input address 


lhld 

adc&?c 



endm 



7 

wrm 

macro 

?c 


• • 
f 1 

write d- 

■a converter number "?c" 


shld 

dac&?c 

;?value written 


pop 

h 

;;restore stack 


endm 




Listing 9-7. Stack Machine Opcode Macros 
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The DUP opcode.simply pushes the HL register pair to memory 
since the HL pair is not altered in the 8080 during this operation. 
In the case of the SUM operator, it is assumed that the KDF-10 
programmer has somehow loaded two values to the KDF-10 stack. So 
the HL registers contain the most recently loaded value, and the 
8080 memory stack contains the next-to-most recently stacked value. 
The POP D operation loads the second operand to the DE pair in the 
8080 CPU. Then the topmost value and next to top value are added, 
using the DAD D operation. The resulting operand goes into the HL 
register pair. This is necessary in the KDF-10 emulation because 
the top of the KDF-10 stack is located in the 8080's HL register 
pair. 


The LSR opcode is more complicated. The values must go through 
the accumulator because the 8080 does not support a double precision 
(16-bit) right shift of the HL register pair. Thus, the LSR macro 
contains a REPT loop that generates inline machine code for each 
right shift. The inline machine code performs the right shift by 
first clearing the carry (XRA A), followed by a high-order right 
shift by one bit (MOV A,H followed by RAR), then by a low-order bit 
shift (MOV A,L followed by RAR) . Note that an intermediate bit can 
move from the high-order byte to the low-order byte using the carry 
between high- and low-order byte shifts. 

In Listing 9-7, the RDM and WRM operation codes are defined by 
memory-mapped input/output operations. That is, memory locations 
10 8 OH through 1087H are intercepted external to the 8080 
microprocessor and treated as external read operations. Thus, a 
load from locations 1080H and 1081H to HL is treated as a read from 
A-D device 0, rather than from RAM. This operation is simple to 
perform in the KDF-10 emulation because all program addresses are 
assumed to be below 1000H, so any 8080 address bus values beyond 
1000H must be memory mapped I/O. 

As a result, ADC0 through ADC3 correspond to the locations 
where A-D values 0 through 3 are obtained. Similarly, the D-A 
output values that are written to locations 1090H through 1097H are 
intercepted as memory mapped output values that are sent to the D-A 
converters rather than to RAM. 

The RDM instruction is emulated by simply performing an LHLD 
from the appropriate memory mapped input address, constructed 
through concatenation of the dummy parameter. The HL value is first 
pushed because the KDF-10 RDM opcode performs this task 
automatically. Then the new value is loaded into the HL register 
pair. 


The WRM opcode definition is similar, except the value to write 
is assumed to reside at the top of the KDF-10 stack and thus appears 
in the 8080 HL register pair. The value is written to the memory 
mapped output location, and the value is removed from the HL pair by 
restoring HL from the 8080 stack. 
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To see the actual code generated by each of these macros. 
Listing 9-8 shows the same averaging program as given in Listing 9- 
6, except that the generated 8080 instructions are interspersed 
throughout the listing file. Listing 9-8 is the usual output from 
MAC? Listing 9-6 was generated using the parameter -M, which 
suppresses generated mnemonics. Compare Listings 9-6, 9-7, and 9-8, 
so that you understand the macro expansion processes. 
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AVERAGE THE VALUES WHICH ARE READ FROM ANALOG 
INPUT PORTS, WRITE THE RESULTING VALUE TO ALL 
THE D-A OUTPUT PORTS. 



t 

MACLIB 

SIZ 

STACK ;READ THE STACK MACHINE OPCODES 

20 ;CREATE 20 LEVEL WORKING STACK 

0100 + 


ORG 

100H 

0100+312E01 


LXI 

SP,??0001 

0103+C32E01 


JMP 

??0001 

0106+ 


DS 

20*2 


LOOP: 

RDM 

0 ;READ A-D PORT 0 

012E+E5 


PUSH 

H 

012F+2A8010 


LHLD 

RDM 

ADC0 

1 ;READ A-D PORT 1 

0132+E5 


PUSH 

H 

0133+2A8210 


LHLD 

RDM 

ADC1 

2 ?READ A-D PORT 2 

0136+E5 


PUSH 

H 

0137+2A8410 


LHLD 

RDM 

ADC 2 

3 ?READ A-D PORT 3 

013A+E5 


PUSH 

H 

013B+2A8610 


LHLD 

ADC 3 


} 

ALL FOUR VALUES ARE STACKED, ADD THEM UP 

SUM ;AD3+AD2 

013E+D1 


POP 

D 

013F+19 


DAD 

SUM 

D 

? (AD3+AD2)+AD1 

0140+Dl 


POP 

D 

0141+19 


DAD 

SUM 

D 

7 ( (AD3+AD2)+AD1)+AD0 

0142+D1 


POP 

D 

0143+19 


DAD 

D 


i 

SUM IS 
LSR 

AT TOP OF THE STACK, DIVIDE BY 4 

2 ?SHIFT RIGHT TWO = DIV BY 4 

0144+AF 


XRA 

A 

0145+7C 

0146+1F 


MOV 

RAR 

A,H 

0147+67 


MOV 

H, A 

0148+7D 

0149+1F 


MOV 

RAR 

A ,L 

014A+6F 


MOV 

L, A 

014B+AF 


XRA 

A 

014C+7C 

014D+1F 


MOV 

RAR 

A,H 

014E+67 


MOV 

H, A 

014F+7D 

0150+IF 


MOV 

RAR 

A ,L 

0151+6F 


MOV 

WRM 

L , A 

0 7 WRITE RESULT TO D-A PORT 0 

0152+229010 


SHLD 

DAC 0 

0155+E1 


POP 

H 

0156 C32E01 


JMP 

LOOP 7 GO GET ANOTHER SET OF VALUES 


Listing 9-8. Averaging Program with Expanded Macros 
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A problem arose at Nachtflieger MW, however, that had to be 
rectified. Although programs could be effectively written for the 
KDF-10 computer using the 8080 emulation, they could not be 
effectively debugged. The program in Listing 9-8, for example, 
could be tested under the CP/M Dynamic Debugging Tool (see CP/M 
documentation) , but the program required monitoring and tracing at 
the 8080 machine code level. It became clear that higher level 
debugging tools were necessary. 

As a result, Nachtflieger designers added several pseudo 
opcodes that allow debugging traces. The opcodes can be 
interspersed in the program and selectively enabled and disabled, 
depending on the debugging needs. In production, all debugging 
traces are disabled, resulting only in absolute port I/O. The 
additional debugging opcodes are listed below. 


PRN msg Print the message given by "msg" at the debugging 
console whenever the print trace is enabled. The 
message must be enclosed in angle brackets. 

DMP Print the value of the top element in the KDF-10 

stack in hexadecimal. 


TRT t Set machine code trace option to true. Each time a 
KDF-10 machine operation is executed, the opcode is 
printed, followed by the approximate KDF-10 machine 
code address, followed by the top two elements of 
the KDF-10 stack, in the format: 

OPC oploc top top' 

where OPC is the opcode, oploc is the location, top 
is the top element, and top' is the second to the 
top element, all in hexadecimal notation. 

TRF t Disable the machine code trace. Only the KDF-10 
instructions that physically appear between the TRT 
and TRF opcodes are shown in the trace. 

TRT p Enable the print/read trace. PRN opcodes that follow 
produce output at the debugging console, and are 
otherwise treated as comments. Further, RDM and WRM 
opcodes prompt and display data at the debugging 
console. 


TRF p Disable the print/read trace. Only the PRN, RDM, and 
WRM instructions that physically appear between TRT 
and TRF interact with the console. 


The traces are disabled at the beginning of the program and must be 
explicitly enabled with TRT opcodes. 
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AVERAGING PROGRAM WITH INTERSPERSED DEBUG CODE 




MACLIB 

DSTACK 

;READ THE STACK MACHINE OPCODES 

0000 


SIZ 

20 

?CREATE 20 LEVEL WORKING STACK 

0103 


TRT 

T 

;MACHINE CODE TRACE ON 

0103 


TRT 

P 

;PRINT TRACE ON 

0103 


PRN 

<TRACE FOR AVERAGING PROGRAM> 

012E 

LOOP: 

RDM 

0 

;READ A-D PORT 0 

01F0 


DMP 


?WRITE TOP OF STACK 

022C 


RDM 

1 

;READ A-D PORT 1 

0267 


DMP 


;WRITE TOP OF STACK 

026A 


RDM 

2 

;READ A-D PORT 2 

02A5 


DMP 


?WRITE TOP OF STACK 

02A8 


RDM 

3 

;READ A-D PORT 3 

02E3 


DMP 


;WRITE TOP OF STACK 

02E6 


PRN 

<FOUR VALUES HAVE BEEN READ> 


• 

9 

ALL FOUR VALUES 

ARE STACKED, ADD THEM UP 

0310 


SUM 


?AD3+AD2 

0324 


DMP 


?WRITE FIRST SUM 

0327 


SUM 


? (AD 3+AD 2)+AD1 

033B 


DMP 


?WRITE SECOND SUM 

033E 


SUM 


? ( (AD3+AD2)+AD1)+AD0 

0352 


PRN 

<VALUES 

HAVE BEEN ADDED> 

0378 


DMP 


?WRITE SUM OF VALUES 


• 

9 

SUM IS 

AT TOP OF THE STACK, DIVIDE BY 4 

037B 


LSR 

2 

;SHIFT RIGHT TWO = DIV BY 4 

0389 


PRN 

<AVERAGE VALUE CALCULATED> 

03B1 


DMP 


?WRITE AVERAGE VALUE 

03B4 


WRM 

0 

;WRITE RESULT TO D-A PORT 0 

03EE 


BRN 

LOOP 

;GO GET ANOTHER SET OF VALUES 

03F1 


XIT 


;EMIT EXIT CODE 


Listing 9-9. Averaging Program with Debugging Statements 


Listing 9-9 shows the averaging program of Listing 9-6 with 
interspersed debugging statements. The opcodes TRT t and TRT p are 
executed at the beginning of the program, enabling all trace options 
throughout the execution. The PRN statement above the LOOP label 
prints the initial sign-on? the DMP statements after each read 
operation give the value of the A-D port. Upon completion of the 
four-element read, the PRN opcode indicates this fact. Each SUM 
operator is followed by a DMP opcode that shows the current sum. 
Finally, the PRN and DMP opcodes display the final average value 
that is being sent to D-A port 0. The XIT opcode shown at the end 
of the program is discussed below. 

Listing 9-10 shows the execution of the averaging program under 
DDT. Note that the program headings appear at the points in the 
program where PRN opcodes are placed. Further, the console is 
prompted for input in the case of an RDM opcode, giving the absolute 
memory mapped input address in decimal, while the WRM instruction 
produces a "D-A OUTPUT . ." message that shows the absolute memory 
mapped output address and the data that is written. 
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The opcodes are also traced showing the opcode mnemonic, 
address, and top two stacked elements. The RDM trace at the 
beginning, for example, shows the instruction address 01AD, which is 
in the range of the first RDM of Listing 9-9 (012E to 01EF) , and is 
followed by the two values 0111 (the value just read) and C21D 
(garbage value, because only one element is stacked). The trace is 
easily followed at the KDF-10 level, showing each value that is read 
in and the operations performed upon these values. Upon completion 
of the debugging process under CP/M, the TRT opcodes are removed and 
the program is reassembled, leaving only the 8080 instructions 
required in the production machine. Nachtflieger systems engineers 
then take the resulting program and test its operation in a hardware 
environment. 


A>ddt aver.hex 
DDT VERS 1.4 
NEXT PC 
0406 0000 

-glOO 

TRACE FOR AVERAGING PROGRAM 
A-D INPUT AT 4224 111 
RDM 01AD 0111 C21D 
(TOP)= 0111 

A-D INPUT AT 4226 222 
RDM 0255 0222 0111 
(TOP)= 0222 

A-D INPUT AT 4228 555 
RDM 0293 0555 0222 
(TOP)= 0555 

A-D INPUT AT 4230 444 
RDM 02D1 0444 0555 
(TOP)= 0444 

FOUR VALUES HAVE BEEN READ 
SUM 0312 0999 0222 
(TOP)= 0999 
SUM 0329 0BBB 0111 
(TOP)= 0BBB 
SUM 0340 0CCC C21D 
VALUES HAVE BEEN ADDED 
(TOP)= 0CCC 

AVERAGE VALUE CALCULATED 
(TOP)= 0333 

D-A OUTPUT AT 4240 0333 
WRM 03DC 793B C21D 
A-D INPUT AT 4224 

Listing 9-10. Sample Execution of AVER Using DDT 
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Nachtflieger engineers quickly realized that the KDF-10 design 
had a number of deficiencies due to the paucity of arithmetic 
operators and the total absence of conditional branching 
instructions. Further, there was no provision for variable storage 
other than the stack. Thus, the KDF-11 naturally evolved from the 
KDF-10, incorporating these features. Table 9-1 lists the operation 
codes of the KDF-11. 


Table 9-1. KDF-11 Operation Codes 


Code 


Meaning 


DCL v,n Declare (reserve) storage for a variable 

by the name v, with optional size n. If n 
is omitted, then n - 1 is assumed. All 
DCL opcodes must follow the XIT opcode 
given below. 


LIT c 


Load the value of the literal constant c 
to the top of the KDF-11 stack. 


VAL v,i,c Load the value of the variable v 

optionally indexed by the variable i with 
the optional constant offset c. VAL V 
loads the value of V to the top of the 
stack. VAL V,I loads the value located at 
the address of V plus the index value 
contained in I. VAL V,I,3 loads the value 
at location V plus the index I, plus the 
constant index 3. In all cases, the value 
is placed at the top of the KDF-11 stack. 


STO v,i,c Store the value obtained from the KDF-11 

stack to the address given by v, plus the 
optional index i, plus the optional 
constant index given by c. The top 
element of the KDF-11 stack is removed. 


DIF Subtract the top element of the KDF-11 

stack from the next-to-top element of the 
stack and replace both operands by their 
difference.* 

GEQ a Test the next-to-top element (top') 

against the top of stack element (top) , 
and branch to the label given by "a" if 
top* is greater than or equal to top. If 
not, program control continues to the next 
opcode in sequence. 
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Table 9-1. 

(continued) 

Code 


Meaning 

BRN a 

Replace the JMP instruction in the KDF-10 
architecture to allow complete separation 
of the KDF-11 and 8080 machines. 


Listing 9-11 gives the macro library that was constructed by 
the Nachtflieger software group for KDF-11 machine emulation. More 
than half of the macro library implements trace and debugging 
functions. The remaining components implement the KDF-11 opcodes 
themselves. Each major section of this macro library, called 
DSTACK.LIB, is briefly described below, followed by an example of 
its use. 
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macro 

****** 

* 

****** 


library 

******** 

begin 

******** 


bdos 

equ 

0005h 

rchar 

equ 

1 

wchar 

equ 

2 

wbuf f 

equ 

9 

tran 

equ 

lOOh 

data 

equ 

llOOh 

cr 

equ 

Odh 

If 

equ 

Oah 

7 

debugt 

set 

0 

debugp 

set 

0 

7 

prn 

macro 

pr 


msg: 

pmsg: 


print 

if 

local 

jmp 

db 

db 

push 

lxi 

mvi 

call 

pop 

end if 

endm 


for a zero address machine 
*************************** 
trace/dump utilities * 

*************************** 

;system entry 
jread a character 
;write character 
jwrite buffer 
;transient program area 
;data area 
;carriage return 
;line feed 

;;trace debug set false 
;;print debug set false 


message 1 pr' at console 
debugp ;;print debug on? 
pmsg,msg ;;local message 

pmsg ;;around message 

cr,lf ;;return carriage 

1 &PR$ 1 ;;literal message 

h j;save top element of stack 

d,msg jj local message address 
c,wbuff ;;write buffer 1 til $ 
bdos ;;print it 

h ;;restore top of stack 

;;end test debugp 


ugen 
7 7 

@ch: 


@nb: 


i i 

@hx: 


macro 

generate utilities for trace or dump 
local psub 

jmp psub ;?jump past subroutines 

;jwrite character in reg-a 
mov e,a 

mvi c,wchar 

jmp bdos ;;return thru bdos 

;jwrite nibble in reg-a 

adi 90h 

daa 

aci 40h 

daa 

jmp @ch jj return thru @ch 

jjwrite hex value in reg-a 
push psw j j save low byte 

rrc 
rrc 


Listing 9-11. Stack Machine Macro Library 
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7 7 
@ad 


@in: 


@inO: 


@inl: 


7 7 

psub: 
ugen 
7 7 


rrc 

rrc 

ani 

Of h 

?;mask high nibble 

call 

@nb 

;?print high nibble 

pop 

psw 


ani 

Of h 


jmp 

@nb 

??print low nibble 

7?write address 

value in hi 

push 

h 

;? save value 

mvi 

a,' ' 

7 7leading blank 

call 

@ch 

??ahead of address 

pop 

h 

??high byte to a 

mov 

a,h 


push 

h 

?;copy back to stack 

call 

@hx 

;?write high byte 

pop 

h 


mov 

a, 1 

?;low byte 

jmp 

@hx 

;?write low byte 

;? read 

hex value to hi from console 

mvi 

a, V ' 

?7 leading space 

call 

@ch 

7 7 to console 

lxi 

h, 0 

?7 starting value 

push 

h 

?7 save it for char read 

mvi 

c,rchar 

?7 read character function 

call 

bdos 

?7 read to accumulator 

pop 

h 

??value being built in hi 

sui 

•O' 

7?normalize to binary 

cpi 

10 

? 7 decimal? 

jc 

@inl 

? 7 carry if 0 , 1,...,9 

may be 

hexadecimal a,...,f 

sui 

'A'-'O'- 

•10 

cpi 

16 

7 ?a through f? 

rnc 


7 ?return with assumed cr 

?;in range, multiply by 4 and add 

rept 

4 


dad 

h 

??shift 4 

endm 

ora 

1 

7 ?add digit 

mov 

1 f a 

7?and replace value 

jmp 

@in0 

7 ?for another digit 


macro 

redef to include once 
endm 

ugen ?;generate first time 
endm 


Listing 9-11. (continued) 
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trace 


7 7 


@tl: 
@t2: 


***************************************** 

* end of trace/dump utilities * 

* begin trace (only) utilities 
***************************************** 
macro code,mname 

trace macro given by mname, 
at location given by code 


local 

ugen 

psub 

7 7generate 

utilities 

jmp 

ds 

psub 

2 

7 7 temp for 

reg-1 

ds 

2 

7 7 temp for 

reg-2 


@tr: 


;;trace 

bc=code 

shld 

pop 

xthl 

shld 

push 

push 

mvi 

call 

pop 

call 

lhld 

call 

lhld 

call 

pop 

pop 

lhld 

push 

push 

lhld 

ret 


macro call 
address, de=message 
@tl ;;store top reg 

h ;;return address 

7?reg-2 to top 
@t2 ;;store to temp 

psw ??save flags 

b ?;save ret address 

c,wbuff ? 7print buffer func 

bdos 77print macro name 

h 77 code address 

@ad ?;printed 

@tl 7? top of stack 

@ad 77 printed 

@t2 77 top-1 

@ad 77printed 

psw 77 flags restored 

d 77 return address 

@t2 7 ; top-1 

h 77 restored 

d 77 return address 

@tl ;?top of stack 


7 7 

psub: 


77past subroutines 


7 7 

trace 
7 7 


msg: 


macro c,m 

redefined trace, uses @tr 
local pmsg,msg 

jmp pmsg 

db cr,If ? 7 cr,If 

db '&M$' 7 ? mac name 


pmsg: 

lxi b,c 77Code address 

lxi d,msg 77macro name 

call @tr ??to trace it 

endm 


Listing 9 - 11 . (continued) 
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7 7 

back 

to original macro level 


trace 

code,mname 


endm 


trt 

macro 

f 

7 7 

turn on flag "f" 

debug&f 

set 1 7 7 print/trace on 


endm 


trf 

macro 

f 

7 7 

turn off flag "f" 

debug&f 

set 0 77 trace/print off 


endm 


? tr 

macro 

m 

7 7 

check 

debugt toggle before trace 


if 

debugt 


trace 

%$ ,m 


endm 


7 

***************************************** 

7 

* 

end trace (only) utilities * 

7 

* 

begin dump (only) utilities * 

7 

***************************************** 

dmp 

macro 

vname,n 

7 7 

dump variable vname for 

7 7 

n elements (double bytes) 


local 

psub 77 past subroutines 


ugen 

??gen inline routines 


jmp 

psub 77past local subroutines 

@dm: 

??dump utility program 

7 7 

de=msg 

address, c=element count 

7 7 

hl=base address to print 


push 

h 77 base address 


push 

b 77 element count 


mvi 

c,wbuff ??write buffer func 


call 

bdos 7?message written 

@dmO: 

pop 

b ??recall count 


pop 

h 7?recall base address 


mov 

a,c ??end of list? 


ora 

a 


rz 

7?return if so 


dcr 

c 7 7 decrement count 


mov 

e,m 77 next item (low) 


inx 

h 


mov d,m ;;next item (high) 

i nx h ??ready for next round 

P us h h ?;save print address 

push b 7;save count 

xchg 77 data ready 

call @ad 7 7print item value 

jmp @dmO 77 for another value 
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f 7 

@dt: 

;;dump 

top of stack only 


prn 

<(top)=> ? ?" (TOP)*" 


push 

h 


call 

@ad ;;value of hi 


pop 

h ??top restored 

7 7 

ret 


psub: 



f 7 

dmp 

macro 

?v,?n 

• • 

/ / 

redefine dump to use @dm utility 


local 

pmsg ,msg 

• • 

11 

special 

case if null parameters 


if 

nul vname 

7 7 

dump the top of the stack only 


call 

@dt 


exitm 



endif 


7 7 

otherwise dump variable name 


jmp 

pmsg 

msg: 

db 

cr,lf ;;crlf 


db 

1 &?V =$ 1 ?;message 

pmsg: 

adr 

? v ;;hl=address 

active 

set 

0 ;;clear active flag 


lxi 

d,msg ;;message to print 


if 

nul ?n ;?use length 1 


mvi 

c f l 


else 



mvi 

c,?n 


endif 



call 

@dm ??to perform the dump 


endm 

;;end of redefinition 


dmp 

vname,n 


endm 


I 

**************************************** 

• 

$ 

* 

end dump (only) utilities. 


* 

begin stack machine opcodes 

1 

**************************************** 

active 

set 

0 ;active register flag 

7 

siz 

macro 

size 


org 

tran ??set to transient area 

.. 

create 

a stack when "xit" encountered 

@stk 

set 

size ;;save for data area 


lxi 

sp,stack 


endm 
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save 
7 7 

save 

active 

7 

rest 
7 7 

active 

7 

clear 
7 7 

active 

del 
7 7 

vname: 


macro 

check to ensure "enter" properly set up 
if stack ;;is it present? 

endif 

;?redefine after initial reference 
active ?;element in hi 
h ;;save it 


7?set active 


macro 

if 

push 

endif 

set 

endm 

save 

endm 


macro 

restore the top element 

if not active 

P°P h ; ; recall to hi 

endif 

set 1 ? ?mark as active 

endm 

macro 

clear the top active element 
rest 7 ?ensure active 

set 0 7?cleared 

endm 

macro vname,size 
label the declaration 


if 
ds 
else 

ds size*2 

endm 


nul size 

2 ??one word req'd 

?7 double words 


lit 


adr 


macro val 

load literal value to top of stack 
sa Y e ??save if active 

lxi h,val 77 load literal 

?tr lit 

endm 

macro base,inx,con 

load address of base, indexed by inx, 
with constant offset given by con 


save 

if 

lxi 

exitm 

endif 


?7 push if active 
nul inx&con 

h,base ??address of base 
7?simple address 
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t 

val 
7 ? 

} i 


r 

sto 
? } 

I I 


must be 

if 

lxi 

else 

lhld 

dad 

if 

lxi 

dad 

endif 

endif 

lxi 

dad 

endm 


inx and/or con 
nul inx 

h,con*2 ;;constant 


inx 

h 

not nul 
d,con*2 
d 


d,base 

d 


;;index to hi 

;;double precision inx 

con 

;;double const 
;;added to inx 
;;not nul con 
;;nul inx 
;;ready to add 
;;base+inx*2+con*2 


macro b,i,c 

get value of b+i+c to hi 

check simple case of b only 


if 

nul i&c 


save 


;;push if active 

lhld 

else 

b 

;;load directly 

"adr" 

pushes active registers 

adr 

b, i,c 

;;address in hi 

mov 

e,m 

;;low order byte 

inx 

h 


mov 

d r m 

;;high order byte 

xchg 

endif 


;;back to hi 

? tr 
endm 

val 

;;trace set? 

macro 

b, i,c 



store the value of the top of stack 
leaving the top element active 


if 

nul i&c 


rest 


;;activate stack 

shld 

b 

;;stored directly to b 

else 

adr 

b, i,c 

;;value is in de 

pop 

d 

mov 

m f e 

;;low byte 

inx 

h 


mov 

endif 

m,d 

;;high byte 

clear 


;;mark empty 

? tr 
endm 

sto 

;;trace? 
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macro 

rest ;;restore if saved 

add the top two stack elements 

pop d ;;top-1 to de 

dad d ;;back to hi 

?tr sum 

endm 


dif 


macro 

compute difference between top elements 


rest 

pop 

mov 

sub 

mov 

mov 

sbb 

mov 


d 

a,e 

1 

Ira 

a, d 
h 

h, a 


;restore if saved 
;top-1 to de 
;top-1 low byte to a 
?low order difference 
?back to 1 
;top-1 high byte 
;high order difference 
;back to h 


carry flag may be set upon return 


? tr 
endm 


dif 


lsr macro len 

?; logical shift right by len 


rest 

rept 

xra 

mov 

rar 

mov 

mov 

rar 

mov 

endm 

endm 


len 

a 

a, h 

h f a 
a,l 

Ira 


;;activate stack 
;?generate inline 
;;clear carry 

?;rotate with high 0 


?;back with high bit 


geq 


macro 


lab 


jump to lab if 
equal to (top) 
dif 
clear 
?tr 
jnc 

jz 


(top-1) is greater or 
element. 

;;compute difference 
;;clear active 


geq 
lab 
lab 

drop through if neither 
endm 


?;no carry if greater 
;;zero if equal 


dup 


macro 
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duplicate the top element in the stack 


rest 
push 
? tr 
endm 


h 

dup 


;;ensure active 


brn 

macro 

addr 

$ 7 

branch 

to address 


jmp 

addr 


endm 


xit 

macro 

?tr 

xit ;;trace on? 


jmp 

0 ;;restart at 0000 


org 

data ;;start data area 


ds 

@stk*2 ;?obtained from "siz" 

stack: 

endm 


0 

***************************************** 

0 

* 

memory mapped i/o section * 


***************************************** 

0 

input 

values which are read as if in memory 

adcO 

equ 

1080h ;a-d converter 0 

add 

equ 

1082h ?a-d converter 1 

adc2 

equ 

1084h ;a-d converter 2 

adc3 

equ 

1086h ;a-d converter 3 

dacO 

equ 

1090h ;d-a converter 0 

dacl 

equ 

1092h ?d-a converter 1 

dac2 

equ 

1094h ;d-a converter 2 

dac3 

equ 

1096h ;d-a converter 3 

0 

rwtrace 

macro msg,adr 

} 7 

read or write trace with message 

7} 

given 

by "msg" to/from "adr" 


prn 

<msg at adr> 


endm 


rdm 

macro 

?c 

• • 

# / 

read a 

-d converter number "?c" 


save 

;;clear the stack 


if 

debugp ;;stop execution in ddt 


rwtrace <a-d input >,% adc&?c 


ugen 

;;ensure @in is present 


call 

@in ;? value to hi 


shld 

else 

adc&?c ;;simulate memory input 

• • 

/ f 

read from memory mapped input address 


lhld 

endif 

adc&?c 


?tr 

endm 

rdm ;?tracing? 
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wrm 


?c 

■a converter number "?c" 

;?restore stack 
debugp ;;trace the output 
<d-a output> ,% dac&?c 

??include subroutines 
@ad 7 ?write the value 

dac&?c 

wrm 7 ?tracing output? 

?7 remove the value 

********************************* 

end of macro library * 

***************************************** 


macro 
write d- 
rest 
if 

rwtrace 
ugen 
call 
endif 
shld 
?tr 
clear 
endm 
******** 
* 


Listing 9-11. (continued) 


The first portion of the library, which is principally 
concerned with debugging functions, begins with CP/M system calls, 
function numbers, and equates for nongraphic characters, similar to 
the examples given earlier. Although these values are not necessary 
for operation of the KDF-11, they are necessary for the debugging 
functions that operate when the TRT opcode is in effect. Following 
the CP/M equates, the toggles DEBUGT and DEBUGP are set to false (0 
value), reflecting the conditions of the debugging switches given by 
TRT and TRF. When DEBUGT is true (1 value) , machine operation codes 
are traced. Similarly, when DEBUGP is true, PRN, RDM, and WRM 
operations interact with the console. 

The PRN macro, for example, produces an inline message with a 
call to CP/M to write the message whenever the DEBUGP toggle is 
true. Otherwise, the PRN produces no generated code. 

The UGEN macro that follows PRN is called the first time the 
debugging subroutines are required by trace or print/read opcodes. 
When invoked, the UGEN macro produces several inline subroutines 
that are used throughout the debugging process. If no trace or 
print/read functions are invoked during the assembly, UGEN is not 
invoked. Thus no inline subroutines are included for debugging. If 
UGEN is invoked, the subroutines shown below are included inline: 


@CH writes a single ASCII character to the console. 

@NB writes a single half byte (nibble) to the 

console. 

@HX writes a full hexadecimal byte value at the 

console. 

@AD writes a full address (double byte) value with 

preceding blank. 
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@IN reads a hexadecimal value from the console to 
HL. 

Upon including these subroutines, UGEN then redefines itself to an 
empty macro body so that the subroutines are not included on 
subsequent invocations of UGEN. This ensures that the inline 
subroutines are included only once, and only if they are required by 
the debugging macros. 

The SIZ macro is similar to the opcode defined for the KDF-10, 
except that the size of the stack is saved for later declaration in 
the data area (see the XIT opcode). Throughout the opcode macros, 
the SAVE and REST macros save and restore the HL register pair, 
based on the ACTIVE flag. The CLEAR macro, however, marks the top 
element of the KDF-11 stack as deleted. 

The DCL macro simply sets up the variable name VNAME as a label 
and follows the label by a DS that reserves the specified number of 
double words. The DCL opcodes must all occur at the end of the KDF- 
11 program, following the XIT opcode. 

The LIT opcode is emulated with a macro that first SAVEs the 
stack top, possibly generating an HL push. The literal value is 
then loaded directly into the HL register pair. The ACTIVE flag is 
set on completion of this macro because SAVE always marks HL as 
active. 

The ADR macro is a utility macro used in the VAL, STO, and DMP 
opcodes to build the address of a particular variable, with optional 
variable and constant offsets, in the HL register pair. Based on 
the optional parameters, ADR either loads the base address directly 
to the HL pair or constructs the address using HL and DE for 
indexing. Thus, the following invocations of ADR (in the left 
column) produce the machine code in the right column. 


ADR 

X 

LXI 

H, X 

ADR 

X,I 

LHLD 

I 



DAD 

H 



LXI 

D, X 



DAD 

D 

ADR 

X,I,3 

LHLD 

I 



DAD 

H 



LXI 

D, 6 



DAD 

D 



LXI 

D, X 



DAD 

D 

ADR 

X,,3 

LXI 

H, 6 



LXI 

D, X 



DAD 

D 
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The final address for the optionally indexed variable remains in the 
HL register pair. The code within the ADR macro can be improved 
slightly by providing a constant offset. That is, the following 
invocations in the left column produce the machine code in the right 
column by redefining the ADR macro. 


ADR 

X,1,3 

LHLD 

I 



LXI 

D, X+6 



DAD 

D 

ADR 

X,,3 

LXI 

H ,X+6 


As an exercise, redefine ADR to generate this improved machine 
code sequence. 

The VAL macro loads a variable value to the stack. STO stores 
the top of stack value to memory. ADR constructs the address of the 
variable whenever optional indexing is specified. Otherwise, LHLD 
or SHLD directly accesses the variable. Again, slight improvements 
in generated code can be obtained by providing a constant offset 
with no variable index. 

The opcodes LIT, VAL, and STO all end with an invocation of the 
?TR macro which, as discussed above, checks the DEBUGT flag. If 
true, the ?TR macro invokes TRACE with the machine code address and 
opcode name for display at the debugging console. The ?TR macro 
invocation produces no machine code trace when DEBUGT is false. 

The SUM opcode first invokes REST to ensure that the HL 
register pair contains the topmost KDF-11 element. The second to 
top element is then loaded to the DE pair and added to HL, producing 
an active KDF-11 element in HL. ACTIVE is true at this point 
because REST always leaves the flag set to true. 

The DIF opcode definition is similar to SUM, except that the 
8080 accumulator computes the 16-bit difference between the top two 
KDF-11 stacked elements. 

The LSR macro defines the KDF-11 logical shift right operation. 
The REST macro is first invoked to ensure that HL is active, 
followed by a repetition of the machine code required to perform a 
16-bit right shift of the HL register pair. In the case of a long 
shift, there is a considerable amount of inline machine code for the 
operation. Thus, it is a useful exercise to redefine LSR, so that 
it generates an inline subroutine to perform the shift operation for 
values of LEN sufficiently large to warrant the subroutine call. 
Although this requires a subroutine set up and call, the amount of 
generated code can be reduced significantly for programs that make 
heavy use of the LSR operator. 

The GEQ macro follows the LSR definition and allows conditional 
branching to the specified label address. GEQ begins by computing 
the difference between the top two elements of the KDF-11 stack. 
This has the side-effect of setting the 8080 carry bit if the next 
to top element exceeds the top element in the KDF-11 stack. The ?TR 
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macro eventually leads to the @TR subroutine where the status flags 
(including the carry condition) are saved and restored. Otherwise, 
GEQ could not count on the condition of the carry flag. 

Further, the 8080 A register contains the least significant 
byte of the difference between DE and HL, so the ORA H produces a 
zero result if the difference is zero. To be complete, the KDF-11 
should have a complete range of conditional tests, allowing tests 
for equality (EQL), inequality (NEQ), less than (LSS), greater than 
(GTR), and less than or equal (LEQ). 

The DUP opcode first ensures that the HL register pair is 
active, then duplicates this value by pushing the HL pair to the 
8080 stack, emulating a KDF-11 stack push operation. Note that the 
HL pair is active at the end of the DUP macro due to the invocation 
of REST. 

The BRN and XIT macros follow GEQ. The BRN macro simply 
translates to a jump instruction in the 8080. The XIT macro first 
invokes the ?TR macro to check for machine code tracing. A JMP 0 is 
then emitted, corresponding to a system restart in both CP/M and the 
emulated KDF-11 machine architecture. The XIT macro then produces 
anORG statement that restarts the assembly process in the data area 
of the emulated environment (1000H, or 4096 decimal). The area 
reserved for the stack is then set up, followed by the declaration 
of the label STACK at the top of this reserved area. Note that the 
SAVE macro includes the statement sequence: 

IF STACK ?;is it present? 

END IF 

which ensures that both the SIZ and XIT macros have been included in 
the assembly. If the XIT macro is not included, then the label 
STACK does not appear unless used in the KDF-11 program, and the IF 
STACK test produces an undefined operand (U) error. Further, if the 
XIT operator is used, but the SIZ is not, then the statement DS 
SIZ*2 within XIT produces an undefined operand message. Although 
these tests are by no means complete, they detect the most common 
errors. 

Listing 9-11 also contains the definitions of both the RDM and 
WRM opcodes, based on the memory mapped input/output addresses 
defined by ADC0 through ADC3 for the A-D ports, and DAC0 through 
DAC3 for the D-A ports. The RWTRACE (Read-Write Trace) macro is 
included for tracing the RDM and WRM macros when DEBUGP is true. 
The MSG argument corresponds either to A-D INPUT for the RDM opcode 
or to D-A OUTPUT for the WRM opcode. The ADR argument corresponds 
to the absolute decimal address where the memory mapped input/output 
is taking place. Thus, RWTRACE simply constructs a trace message 
from its two arguments and passes this message to PRN for display at 
the debugging console. 

The RDM macro reads the port given by the argument ?C (0, 1, 2, 
or 3). The HL register pair is pushed, if necessary, by the SAVE 
macro, leaving the active flag set for the RDM. RDM then generates 
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an invocation of the RWTRACE macro to produce the trace message. 
Note that the argument "% ADC&7C" produces the numeric value ADCO, 
ADC 1, ADC2, or ADC3, which is included in the trace message. If the 
% is omitted, only the name, not the value, of the input port 
address is printed. Following the output message, UGEN is invoked 
to ensure that the utility subroutines have been included inline. 
The call to @IN allows you to type a hexadecimal value for the 
simulated A-D input value. This value is subsequently stored to 
memory and left in the HL register pair with ACTIVE true. If DEBUGP 
is not set, then the RDM macro simply loads the HL register pair 
from the appropriate memory mapped input location. Finally, RDM 
invokes ?TR to check for possible opcode tracing. 

The WRM opcode is similar to the RDM opcode, except that the 
REST macro is first invoked to ensure that the HL registers contain 
the top element of the KDF-11 stack. This value is displayed at the 
debugging console if DEBUGP is true and then sent to the appropriate 
memory mapped output location. 

One application of the emulated KDF-11 machine shows the power 
of this instruction set. As a small part of a machine control 
system, a KDF-11 processor monitors the machine tool head motion. 
Nachtflieger engineers connect A-D port 0 to a KDF-11 processor that 
reads the instantaneous velocity of the tool head at 1 millisecond 
(ms) intervals. 

The velocity is provided at the A-D port in micrometer (urn) 
increments, and the processor is synchronized with the input, so 
that it halts until the 1 ms interval has elapsed. Nachtflieger 
engineers also guarantee that the tool head is in motion for no more 
than 100 ms before stopping. Thus, with no variations in velocity, 
if the tool moved at the constant rate of 256 um/ms over 50 
intervals of 1 ms each, total distance traveled by the tool is 

256 um/ms * 50 ms = 1280 um = 1.280 mm 

During its travel, however, the instantaneous velocity of the 
tool head varies according to the roughness of the cut, wear on the 
parts, and start/stop intervals. Nachtflieger uses the data 
collected during a cut to monitor these factors and displays machine 
operator information in both digital and analog forms. A primary 
function of the KDF-11 processor in this case is to collect 
instantaneous velocities during a single cut and hold these values 
for analysis as the tool returns to its starting position. Listing 
9-12 shows a KDF-11 program that includes the data collection phase 
and an analysis phase described below. 

The data collection phase of Listing 9-12 occurs between the 
labels MOVE? and COMP; the analysis phase is found between labels 
COMP and ENDF. The program is bounded by the SIZ operator at the 
beginning and the XIT operator at the end, followed by DCL opcodes 
that reserve data areas. This program also includes debugging PRN, 
DMP, TRT, and TRF opcodes for checking out the program. 
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As for the DCL statements at the end of Listing 9-12, the 
vector V is declared with length 100 (double bytes), which holds the 
collected velocities; I and X are temporary values used during the 
collection and analysis phase. The variable TOTAL is a result 
produced by the analysis, as discussed below. 

The program collects data by performing the following steps. 
The variable I is first initialized to 0, corresponding to the first 
velocity V(0) . The program then examines the A-D input port for the 
first nonzero velocity, waiting for the tool head to begin its 
travel. When the first nonzero velocity is read, the collection 
process proceeds by storing the first value at V(0). The index 
value I is then moved along as data items are read, with values 
placed into V(l), V(2), continuing until a zero value is read, 
indicating the tool has ended its travel. 

Referring to Listing 9-12, note that the KDF-11 opcodes listed 
before the label MOVE? initialize the index I by loading a literal 0 
value to the KDF-11 stack, followed by a store into the variable I. 
To follow these operations, the TRT P and TRT T traces are enabled. 
Note, however, that the TRF T opcode stops the machine code trace 
immediately before the MOVE? label. 
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MACLIB 

DSTACK 

;STACK MACHINE SIMULATION 

0000 


SIZ 

50 

;50 LEVEL STACK 

0103 


TRT 

P 

;TURN ON PRN TRACK 

0103 


TRT 

T 

;TURN ON CODE TRACE 

0103 


PRN 

COMPUTATION OF TOOL TRAVEL DISTANCE: 

0136 


LIT 

0 

;INITIALIZE INDEX 

0103 


STO 

I 

?i=o 

01E8 


TRF 

T 

;TURN CODE TRACE OFF 


? 

LOOK FOR STARTING MOTION (NON ZERO VALUE) 


MOVE?: 

; READ A- 

-D CONVERTER FOR NON ZERO 

01E8 


RDM 

0 


0210 


STO 

X 

;HOLD TEMPORARILY 

0213 


VAL 

X 

;RELOAD FOR TEST 

0216 


LIT 

1 

?X GEQ 1 TEST 

021A 


GEQ 

READ 

?X GEQ 1 ? 

0227 

READ: 

BRN 

MOVE? 

;RETRY IF NOT 

022A 


PRN 

<STORE 

FIRST/NEXT VALUE> 

0250 


DMP 

X 


029C 


VAL 

X 

;LOAD FIRST/NEXT VALUE 

029F 


STO 

V,I 

;STORE TO THE ITH ELEMENT 

02 AC 


VAL 

I 

;INCREMENT I 

02 AF 


LIT 

1 


02B3 


SUM 


;I+1 

02B5 


STO 

I 

?I=I+1 

02B8 


LIT 

0 

? 0, FOR 0 GTR X TEST 

02BB 


VAL 

X 

;ZERO VALUE READ? 

02BF 


GEQ 

COMP 

;COMPUTE DISTANCE IF 0 

02CC 


RDM 

0 

;READ ANOTHER DATA ITEM 

02F4 


STO 

X 

;SAVE IT IN X 

02F7 


BRN 

READ 

;TO STORE AND TEST 

02FA 

COMP: 

PRN 

<VALUES 

ARE LOADED> 

031A 


DMP 

V,10 



i 

NOW COMPUTE DISTANCE TRAVELLED BY TOOL 

032D 


LIT 

0 


0330 


DUP 


;TWO ZEROES 

0331 


STO 

I 

;i=0 

0334 


STO 

TOTAL 

;TOTAL=0 

0338 

GETNXT: 

PRN 

COMPUTING NEXT INTERVAL> 

035F 


DMP 

I 


0372 


DMP 

TOTAL 


0389 


DMP 

<V,I>,2 


03A3 


LIT 

0 

;ZERO AT END 

03A6 


VAL 

V,I 

;AT END? 

03B3 


GEQ 

ENDF 

;0 GEQ X(I)? 


Listing 9-12. Program for Tool Travel Computation 
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• 

9 

NOT AT END OF INTERVAL, COMPUTE NEXT TRAPEZO 

03C0 


VAL 

V,I 


03CC 


VAL 

V,I,1 

? V (I) ,V (1+1) 

03DD 


SUM 


; V (I) + V (I +1) 

03DF 


LSR 

1 

; (V(I)+V(I+l)/2 

03E6 


VAL 

TOTAL 

;READY TOTAL 

03EA 


SUM 


;TOTAL=TOTAL+TRAPEZOID 

03EC 


STO 

TOTAL 

;BACK TO SUM 

03EF 


VAL 

I 

?1=1+1 

03F2 


LIT 

1 


03F6 


SUM 



03F8 


STO 

I 

;BACK TO I 

03FB 


BRN 

GETNXT 


03FE 

ENDF: 

PRN 

<END OF 

COMPUTATION> 

0420 


DMP 

TOTAL 


0437 


VAL 

TOTAL 

7LOAD FOR D-A OUTPUT 

043A 


WRM 

0 

7WRITE D-A PORT 

0462 


XIT 




7 

7 

DATA 

AREA 


1164 


DCL 

I 

7 INDEX 

1166 


DCL 

X 

7TEMPORARY 

1168 


DCL 

V,100 

?VELOCITY VECTOR 

1230 


DCL 

TOTAL 

7TOTAL DISTANCE 


Listing 9-12. (continued) 


Following the MOVE? label, A-D port 0 is read and examined for 
the first nonzero value. Each time the port is read, it is stored 
into the temporary variable X, then reloaded and examined for a zero 
value. Because GEQ is the only comparison operator in the KDF-11 
machine, the test is "1 greater than or equal to X." Thus, the 
branch is taken to READ whenever X is 1 or larger. 

Upon encountering the READ label, the value X (just read from 
port 0) is stored into V(I), where I is zero. The value of I is 
then incremented by loading I to the top of the KDF-11 stack, adding 
1 (LIT 1, SUM), and then storing the sum back into I. After 
incrementing I, the program proceeds to check the end of the tool 
travel. X is loaded to the top of the stack, and the test 0 greater 
than or equal to X is performed. If the condition is true, control 
transfers to the label COMP, where the analysis phase begins. 
Otherwise, port 0 is read again, and the value is stored into the 
temporary X. Control then proceeds back to the READ label to store 
the next velocity and test for zero. 

Before 100 intervals have elapsed, the RDM 0 produces a zero 
value that is stored into X and subsequently stored into V(I), for 
the current value of I. Thus, when control arrives at the label 
COMP, the instantaneous velocities are stored in V, terminated by a 
zero. At this point, the analysis of these collected velocities can 
take place. 
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The single function that takes place in the analysis section of 
Listing 9-12 is the computation of the distance traveled by the tool 
through this interval. Nachtflieger engineers have determined that 
it is sufficient to compute the distance traveled by the tool using 
the trapezoidal rule that approximates the actual distance by 
summing the average of each adjacent pair of velocities. The sums 
are formed as shown below: 

V n + Vi . V n +V 0 . ... , V ,+V 
_± t _z + + _n-l_n 

2 2 r 

where n is the last interval to sum. Thus, for example, if the 
velocity is constant at 256 um/ms (which would not occur in 
practice), then 

V ! = V 2 = . . . = V n = 256 

The summing formula given above reduces to 256 * n. Given the 
preceding example, where n = 50 ms, this formula produces the value 
1.280 mm, as given earlier. The velocity values are not usually 
constant, so the numerical integration given by the trapezoidal rule 
is used to obtain an approximation. 

The KDF-11 instructions shown in Listing 9-12 between the COMP 
and ENDF labels perform the numeric integration, given by the 
trapezoidal rule. The temporary I is used to index through the 
velocity vector V until the final zero value is encountered. For 
each interval, the values of two adjacent velocities are summed and 
divided by two. Each result is then summed into TOTAL, where the 
values are accumulated until the final zero velocity is discovered. 

The opcode sequence immediately following COMP places a zero 
value at the top of the KDF-11 stack, then stores this value into 
both the index I and the accumulating sum given by TOTAL. Ignoring 
the trace opcodes, the operations following GETNXT read the starting 
point of the next interval to process into the stack, using VAL V,I 
(value of V, indexed by I). If 0 is greater than or equal to this 
value, then the computation is complete and control goes to the 
label ENDF. Otherwise, the value of V(I) is loaded to the KDF-11 
stack, followed by the value of V(I+1). The loaded values are then 
summed (SUM) and divided by two (LSR 1), producing a value that 
remains in the KDF-11 stack. TOTAL is then loaded and added to this 
partial sum, and the result is stored back to TOTAL. The index 
value I is then incremented to the next interval and processing 
continues back at the loop header GETNXT. 

Upon processing the final zero velocity, control reaches the 
ENDF label where the distance traveled is written to D-A output port 
zero. The output value is sent to external instrumentation, which 
processes the result and displays the distance traveled in a form 
that is readable by the tool operator. 

Debugging statements have been placed throughout the program. 
These can be used to trace the program execution. Listing 9-12 also 
contains TRT operators that have enabled trace code generation. 
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Thus this program, although longer than the final production 
version, can be used to follow execution under CP/M. 

Listing 9-13 shows the execution of the program of Listing 9-12 
under DDT. The messages printed at the debugging console are a 
result of the PRN opcodes distributed throughout the original 
program that were enabled through the TRT P opcode. Further, the 
machine code trace was only enabled for the interval of two 
operation codes (LIT and STO) at the beginning. To test this 
program, simple A-D values were supplied at the console for the 
velocities: 

V Q = 100H, V 1 = 120H, V 2 = 100H, V 3 = 80H, V 4 = 0 

Upon detecting the final 0 value, the trace of Listing 9-13 shows 
the first 10 values of V (the last 5 elements are garbage values), 
followed by a trace of the sum operations for each interval. In 
each case, the pairs of values that are being added are displayed 
(using the DMP opcode), followed by their summed value, along with 
the running total. Upon completion of the distance computation, the 
value 320H is sent to the D-A output port and displayed at the 
console. 

After initial checks under CP/M, Nachtflieger programmers 
remove the TRT and TRF statements from the KDF-11 program and 
reassemble, producing only the absolute input/output instructions 
required for machine tool control. The resulting program, which 
produces much less code than the debugging version, is placed into 
the equipment for further testing and evaluation. 

Listing 9-14 also provides an example of the listing produced 
when all machine code operators are traced. Although the source 
program listing is not shown, it is identical to Listing 9-12 except 
that the TRF T opcode is removed. Because the complete trace is 
quite extensive, only a partial execution is shown in Listing 9-14. 
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A>DDT INTEG.HEX 
DDT VERS 1.4 
NEXT PC 
0465 0000 
-G100 

COMPUTATION OF TOOL TRAVEL DISTANCE 

LIT 0139 0000 0F77 

STO 01D6 0000 0000 

A-D INPUT AT 4224 0 

A-D INPUT AT 4224 100 

STORE FIRST/NEXT VALUE 

X= 0100 

A-D INPUT AT 4224 120 
STORE FIRST/NEXT VALUE 
X= 0120 

A-D INPUT AT 4224 100 
STORE FIRST/NEXT VALUE 
X= 0100 

A-D INPUT AT 4224 80 
STORE FIRST/NEXT VALUE 
X= 0080 

A-D INPUT AT 4224 0 
STORE FIRST/NEXT VALUE 
X= 0000 

VALUES ARE LOADED 

V= 0100 0120 0100 0080 0000 3EC0 BAll C1C9 5EE1 5623 
COMPUTING NEXT INTERVAL 
1 = 0000 
TOTAL= 0000 
V,I= 0100 0120 
COMPUTING NEXT INTERVAL 
1 = 0001 
TOTAL= 0110 
V,I= 0120 0100 
COMPUTING NEXT INTERVAL 
1 = 0002 

V,I= 0100 0080 

COMPUTING NEXT INTERVAL 

1= 0003 

TOTAL= 02E0 

V,I= 0080 0000 

COMPUTING NEXT INTERVAL 

1= 0004 

TOTAL= 0320 

V,I= 0000 3EC0 

END OF COMPUTATION 

TOTAL= 0320 

D-A OUTPUT AT 4240 0320 

Listing 9-13. Sample Execution of Distance Using DDT 
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A>ddt integ.hex 
DDT VERS 1.4 
NEXT PC 
0852 0000 
-glOO 

COMPUTATION OF TOOL TRAVEL DISTANCE 

LIT 026E 0000 CAB1 

STO 030B 0000 0000 

A-D INPUT AT 128 0 

RDM 0344 0000 0000 

STO 0359 0000 0000 

VAL 036E 0000 0000 

LIT 0384 0001 0000 

DIF 039D FFFF 0000 

GEQ 03AF FFFF 0000 

A-D INPUT AT 128 6 

RDM 0344 0006 0000 

STO 0359 0006 0000 

VAL 036E 0006 0000 

LIT 0384 0001 0006 

DIF 039D 0005 0000 

GEQ 03AF 0005 0000 

STORE FIRST/NEXT VALUE 

X= 0006 

VAL 043F 0006 0000 
STO 045E 016F 0000 
VAL 0473 0000 0000 
LIT 0489 0001 0000 
SUM 049D 0001 0000 
STO 04B2 0001 0001 
VAL 04C7 0006 0001 
A-D INPUT AT 128 0 
RDM 0501 0000 0006 
STO 0516 0000 0006 
LIT 052B 0001 0006 
DIF 0544 0005 0001 
GEQ 0556 0005 0001 
STORE FIRST/NEXT VALUE 
X= 0000 

VAL 043F 0000 0001 
STO 045F 0171 0001 
VAL 0473 0001 0001 
LIT 0489 0001 0001 
SUM 049D 0002 0001 
STO 04B2 0002 0002 
VAL 04C7 0000 0002 
A-D INPUT AT 128 
RDM 0501 0000 0000 

Listing 9-14. Partial Listing of Distance with Full Trace 
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In summary, Nachtflieger MW derived several benefits from their 
emulation of the KDF series stack machines. First, there is very 
^ 1 cost involved in designing and altering their machine 
architecture. In fact, current prices for 8080 microcomputers might 
preclude the custom LSI version of the KDF-? machine. A second 
advantage of the KDF emulation is that the KDF programs are highly 
independent from the host processor. If a higher performance or 
less expensive processor becomes available to Nachtflieger, the 
existing programs can be used intact by changing only the macro 
definitions for each of the KDF opcodes and reassembling using MAC. 


Finally, machine emulation through macro defined operation 
codes offers a distinct advantage over interpretive approaches 
because each opcode translates to only a few host machine 
operations. Interpretive execution often involves ratios of 1000 to 
20,000 emulated instructions per host instruction? macro based 
opcodes are often in a ratio of less than 10 to 1. Further, 
interpretive processors usually require run-time support consisting 
of a predefined general purpose subroutine package that is included 
for each and every program. For a wide variety of microcomputer 
applications, machine emulation through macro defined opcodes offers 
distinct advantages over alternative approaches. 


9.3 Program Control Structures 


Macro facilities can provide program control statements that 
resemble those found in many high-level languages. In general, 
program control statements allow Boolean tests and conditional 
branching based on the outcome of the Boolean test. Further, label 
names usually provided by you as the destination of a branch are 
automatically generated for the particular statement. 


The following paragraphs discuss three typical control 
statements are presented that allow simple conditional grouping 
(WHEN-ENDW), controlled iteration (DO-ENDDO), and case selection 
(SELECT-ENDSEL) . All three statements are program control 
facilities that allow well-structured programming, resulting in 
programs that are easier to write, debug, and maintain. 


Two libraries are first introduced as a foundation for the 
discussion. The I/O library shown in Listing 9-15 allows simple 
character input operations along with full message output. The READ 
macro accepts a single character from the console keyboard and 
stores this character into the variable given by the parameter VAR. 
The WRITE macro shown in Listing 9-15 takes an ASCII message as a 
parameter and sends this message to the console output device 
preceded by a carriage return line-feed sequence. These simple I/O 
macros are stored in the disk in the file SIMPIO.LIB and are used in 
the examples that illustrate the control structures. 
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The second library used in the control structure examples is 
given in Listing 9-16. Collectively, these macros define a number 
of Boolean operations that are performed on 8-bit operands, 
providing the basic relational operations on unsigned integer 


including 

: 


LSS 

less than 


LEQ 

less than or 

equal to 

EQL 

equal to 


NEQ 

not equal to 


GEQ 

greater than 

or equal to 

GTR 

greater than 



In all cases, the macros accept three actual parameters. The 
parameters consist of two data values involved in the test (X and 
Y), along with a program label that receives control if the Boolean 
test produces a true value (TL). The first operand X can be a 
labeled memory location containing an 8-bit value, and Y can be 
either a labeled 8-bit location or a literal numeric value. If the 
first operand X is not supplied, then the value to be tested is 
assumed to exist in the 8080 accumulator when the macro is entered. 
Thus, for example, the macro invocation 

LSS ALPHA,BETA,TRUECASE 

compares the values stored at the labeled memory locations ALPHA and 
BETA, defined by a DS or DB statement, and transfers to the program 
step labeled by TRUECASE if ALPHA contains a value less than the 
value stored at BETA. The invocation 

LSS ,BETA,TRUECASE 

is similar, but it compares the contents of the 8080 accumulator 
with the value stored at BETA. Finally, the invocation 

LSS ALPHA,34,TRUECASE 

compares ALPHA with the literal value 34 in the relational test. 

The macro TEST? is used throughout the macro library to 
construct the relational test by first loading the initial operand 
X, if necessary. The second operand type is then examined by 
executing an IRPC within the TEST? macro of Listing 9-16. This 
extracts the first character of the Y operand. This first character 
must be either numeric or alphabetic. If numeric, then the literal 
value is subtracted from the accumulator, setting the 8080 condition 
codes. If the first character of Y is nonnumeric, then the value is 
assumed to reside in memory. In this case, the HL registers are set 
to the Y operand and the value at Y is subtracted from the 
accumulator value. In any case, the 8080 condition codes are set as 
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a result of the subtraction operation. These condition codes are 
then used in the individual macros to produce conditional jumps to 
the destination labels. These macros are collectively stored on the 
disk in a file named COMPARE.LIB for use in examples that follow. 


7 

macro 

library for simple i/o 

bdos 

equ 

0005h ;bdos entry 

conin 

equ 

1 ;console input function 

msgout 

equ 

9 ;print message til $ 

cr 

equ 

Odh ;carriage return 

If 

equ 

Oah ?line feed 

7 

read 

macro 

var 

7 7 

read a single character into var 


mvi 

c,conin jconsole input function 


call 

bdos ;character is in a 


sta 

var 


endm 


7 

write 

macro 

msg 

7 7 

write 

message to console 


local 

msgl,pmsg 


jmp 

pmsg 

msgls 

db 

cr,lf ;?leading crlf 


db 

'&MSG' ?;inline message 


db 

'$' ;;message terminator 

pmsg: 

mvi 

c r msgout ?;print message til 


lxi 

d,msgl 


call 

endm 

bdos 


Listing 9-15. Simple I/O Macro Library 
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test? 

macro 

x,y 

?? 

utility macro to generate condition codes 


if 

not nul x ?? then load x 


Ida 

x ?; assumed to be in memory 


endif 



irpc 

?y,y ? ? y may be constant operand 

tdig? 

set 

'&?Y'-'O' ;;first char digit? 


exitm 

;;stop irpc after first char 


endm 



if 

tdig? <= 9 ;;y numeric? 


sui 

y 77 yes, so sub immediate 


else 



lxi 

h,y ? ?y not numeric 


sub 

m ??so sub from memory 


endm 


7 

lss 

macro 

x,y,tl 

• • 

9 9 

x lss 

than y test. 

• • 

9 9 

transfer to tl (true label) if true. 

• • 

9 9 

continue if test is false 


test? 

x,y ;;set condition codes 


jc 

tl 


endm 


9 

leq 

macro 

x,y,tl 

7 7 

x less 

; than or equal to y test 


lss 

x,y,tl 


jz 

tl 


endm 


7 

eql 

macro 

x,y,tl 

f 7 

x equal to y test 


test? 

x,y 


jz 

tl 


endm 


7 

neq 

macro 

x,y,tl 

7 7 

x not 

equal to y test 


test? 

x,y 


jnz 

tl 


endm 


7 

geq 

macro 

x,y,tl 

7 7 

x greater than or equal to y test 


test? 

x,y 


jnc 

tl 


endm 



Listing 9-16. Macro Library for Simple Comparison Operations 
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gtr 


macro x,y,tl 
x greater than y test 


local fl 
test? x,y 
jc fl 


false label 


fl: 


dcr a 

jnc tl 

endm 


Listing 9-16. (continued) 


Listings 9-17a and 9-17b show an example of a program that uses 
both the SIMPIO and COMPARE libraries. This program successively 
reads console characters and print messages based on the character 
typed. The program begins by sending the sign-on message at the 
label CYCLE. A character is then read and stored into X, using the 
READ macro. The LSS test determines whether lower- to upper-case 
translation is required, assuming the input is alphabetic. If X is 
numerically less than 61H, the value of a lower-case A, then control 
transfers to the label NOTRAN. Otherwise, the character is loaded 
to the accumulator, the lower-case bit is stripped from the 
character, and it is replaced in memory. Following the label 
NOTRAN, the character is compared with the letters A, B, C, and D. 
In each case, a message is typed corresponding to each letter. If 
one of these four letters cannot be found, the message at ERROR is 
typed. 
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0100 



ORG 

100H 




MACLIB 

SIMPIO ?SIMPLE 10 LIBRARY 




MACLIB 

COMPARE ?COMPARISON OPERATORS 

0100 


CYCLE: 

WRITE 

<TYPE A CHARACTER FROM A TO D > 

012B 



READ 

X 



7 

TEST FOR LOWER CASE ALPHABETIC 

0133 



LSS 

X,61H,NOTRAN 



? 

ARRIVE 

HERE IF X IS GREATER OR EQUAL TO 



7 

A LOWER CASE A (=61H), TRANSLATE 

013B 

3A1102 


LDA 

X 

013E 

E65F 


ANI 

5FH ;CLEAR LOWER CASE BIT 

0140 

321102 


STA 

X 7 STORE BACK TO X 



NOTRAN 

: 




7 

NOW CHECK CASES 

0143 


7 

NEQ 

X,%'A',NOTA 

014B 



WRITE 

<YOU TYPED AN A> 

0167 

C30001 


JMP 

CYCLE 

016A 


NOTA: 

NEQ 

X,%'B',NOTB 

0172 



WRITE 

<YOU TYPED A B> 

018D 

C30001 


JMP 

CYCLE 

0190 


NOTB: 

NEQ 

X,%'C',NOTC 

0198 



WRITE 

<YOU TYPED A C> 

01B3 

C30001 


JMP 

CYCLE 

01B6 


NOTC: 

NEQ 

X,%'D',ERROR 

01BE 



WRITE 

<YOU TYPED A D> 

01D9 



WRITE 

<BYE"l> 

01EB 

C9 


RET 


01EC 


ERROR: 

WRITE 

<NOT AN A, B, C, OR D> 

020E 

C30001 


JMP 

CYCLE 

0211 


7 

X: 

DS 

1 7 temp FOR CHARACTER 

0212 



END 



Listing 

9-17a. 

Single 

Character Processing using COMPARE 


In comparing each letter, the macro NEQ starts with the first 
argument corresponding to the character typed at the console (X); 
the second argument corresponds to the letter to match. The % 
operator in each case produces the numeric value of the character. 
This is necessary because the TEST? macro expects either a number or 
a label value in the second argument position. The program 
processes characters until a D is typed when it returns to the 
Console Command Processor. The intention here is to show the use of 
Boolean tests used by the control structure macros that follow. 

Listing 9-17b shows a partial expansion of the macros given in 
the previous example. The first message expansion is shown, along 
with the READ and NEQ macros. The listing has been abstracted. 
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however, and does not show the macro library statements or the 
remainder of the program following the NOTA label. 



CYCLE: WRITE 

<TYPE A CHARACTER FROM A TO D > 

0100+C32301 

JMP 

?? 0002 

0103+0D0A 

?? 0001 : 

DB CR, LF 

0105+5459504520 DB 

'TYPE A CHARACTER FROM A TO D ' 

0122+24 

DB 


0123+0E09 

?? 0002 : 

MVI C,MSGOUT 

0125+110301 

LXI 

D,??0001 

0128+CD0500 

CALL 

BDOS 


READ 

X 

012B+0E01 

MVI 

C f CONIN 7 CONSOLE INPUT FUNCTION 

012D+CD0500 

CALL 

BDOS 7 CHARACTER IS IN A 

0130+321102 

STA 

X 


. TE st FOR LOWER CASE ALPHABETIC 


LSS 

X,61H,NOTRAN 

0133+3A1102 

LDA 

X 

0136+D661 

SUI 

61H 

0138+DA4301 

JC 

NOTRAN 


; ARRIVE 

HERE IF X IS GREATER OR EQUAL TO 


? A LOWER 

CASE A (=61H), TRANSLATE 

013B 3A1102 

LDA 

X 

013E E65F 

AN I 

5FH ?CLEAR LOWER CASE BIT 

0140 321102 

STA 

X ?STORE BACK TO X 


NOTRAN: 



? NOW CHECK CASES 


NEQ 

X,%'A',NOTA 

0143+3A1102 

LDA 

X 

0146+D641 

SUI 

65 

0148+C26A01 

JNZ 

NOTA 


WRITE 

<YOU TYPED AN A> 

014B+C35F01 

JMP 

??0004 

014E+0D0A 

??0003: 

DB CR,LF 

0150+594F552054 DB 

'YOU TYPED AN A' 

015E+24 

DB 


015F+0E09 

??0004: 

MVI C,MSGOUT 

0161+114E01 

LXI 

D, ??0003 

0164+CD0500 

CALL 

BDOS 

0167 C30001 

JMP 

CYCLE 


NOTA: NEQ X,%'B',NOTB 


Listing 9-17b. Partial Trace of Listing 9-17a with Macro Generation 
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The macro library shown in Listing 9-18, called NCOMPARE, 
expands upon the basic relational macros by allowing a false branch 
option. Each macro accepts four arguments: the X and Y operands, 
as before, a true label (TL) , and a false label (FL) . It is assumed 
that either the TL or FL is supplied in any invocation of a 
relational operator, but not both. If the TL is supplied, then the 
branch is taken if the relational operator produces a true result. 
Conversely, if the TL label is absent but the FL label is supplied, 
then the branch to FL is taken if the relational operation produces 
a false result. Thus, NCOMPARE expands upon the COMPARE library by 
allowing all of the relational operation and their negations. Using 
the NCOMPARE library, for example, the macro invocation 

LSS X,20, ,FALSELAB 

branches to the label FALSELAB if X is not less than the value 20. 
The negation operations are accomplished within the NCOMPARE library 
by first testing for a null TL operand and, if empty, the relational 
operation is reversed by invoking the appropriate negated macro. 
For example, the LSS macro in Listing 9-18 invokes the GEQ macro, 
which is equivalent to "not LSS" when the TL argument is empty and 
supplies the FL argument to LSS as the TL label to GEQ. These 
negated relational forms are used within the control structures 
described below. 
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test? 
? ? 


tdig? 


lss 


i 

leq 
7 7 


eql 
7 7 


macro library for 8-bit comparison operation 
macro x,y 

utility macro to generate condition codes 
if not nul x ;;then load x 

Ida x ;;x assumed to be in memory 

endif 

irpc ?y,y ??y may be constant operand 

set 'SPY'-'O' ;;first char digit? 

exitm ;;stop irpc after first char 

endm 

if tdig? <= 9 ;;y numeric? 

sui y ??yes, so sub immediate 

else 

lxi h,y ?;y not numeric 

sub m 7 ?so sub from memory 

endm 

macro x,y,tl,fl 

x lss than y test, 

if tl is present, assume true test 

if tl is absent, then invert test 

if nul tl 

geq x,y,fl 

else 

test? x,y ?7 set condition codes 

jc tl 

endm 

macro x,y,tl,fl 

x less than or equal to y test 

if nul tl 

geq x,y,fl 

else 

lss x,y,tl 

jz tl 

endm 

macro x,y,tl,fl 
x equal to y test 
if nul tl 

neq x,y,fl 

else 

test? x,y 

jz tl 

endm 


Listing 9-18. Expanded NCOMPARE Comparison Operators 
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macro x,y,tl,fl 

x not equal to y test 
if nul tl 

eql x,y,f1 

else 

test? x f y 

jnz tl 

endm 

macro x,y,tl,fl 

x greater than or equal to y test 
if nul tl 

lss x,y,fl 

else 

test? x,y 

jnc tl 

endm 

macro x,y,tl,fl 

x greater than y test 
if nul tl 

leq x,y,fl 

else 

local gfl ;;false label 

test? x,y 

jc gfl 

dcr a 

jnc tl 

endm 

Listing 9-18. (continued) 


Listing 9-19a is an example of the use of the NCOMPARE library 
within a program. This program is similar to the previous example, 
but instead checks to ensure that alphabetic translation occurs only 
within the proper range of lower-case letters. Following the label 
CYCLE, the character read from the console is compared with a lower¬ 
case a, using the % operation to produce equivalent decimal value 
97. Because the negated form of GEQ is used here, the label NOTRAN 
receives control if X is not greater than or equal to % , a* . If X is 
greater than or equal to %a, program flow continues to the next test 
in sequence where X is compared with a lower-case z (% , z , = decimal 
122) . In this case, the normal form of GTR is used. Control 
transfers to NOTRAN if X is greater than %'z', which is above the 
range of lower-case alphabetics. If X is between %'a' and %'z*, the 
character is changed to upper-case, as before, by removing the 
lower-case bit and replacing X in memory. Note that the indentation 
levels between the GEQ and GTR operations are included for 
readability of the program. 

Listing 9-19b shows the GEQ-GTR section of the program of 
Listing 9-19a with full macro trace enabled. (See Section 10.) The 
trace in this listing shows the transition from GEQ to the LSS 
operator, substituting the FL label in place of the TL label. 
Again, the macro library statements are not shown, and the listing 
following the NOTRAN label is not present. 
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neq 
7 7 


geq 

77 


gtr 


gf Is 




Programmer * s 

Utilities 

Guide 

9.3 Program Control Structures 

0100 



ORG 

100H 




MACLIB 

SIMPIO ?SIMPLE IO LIBRARY 




MACLIB 

NCOMPARE;COMPARISON OPERATORS 

0100 


CYCLE: 

WRITE 

<TYPE A CHARACTER FROM A TO D > 

012B 



READ 

X 

0133 


; 

TEST FOR LOWER CASE ALPHABETIC 



GEQ 

X,%'a',,NOTRAN ;BRANCH ON FALSE 



r 

X IS GREATER OR EQUAL TO LOWER CASE A 

013B 




GTR X,%'Z',NOTRAN 

0147 

3A1D02 



LDA X 

014A 

E65F 



ANI 5FH ;UPPER CASE 

014C 

321D02 



STA X ;BACK TO X 



NOTRAN: 





t 

NOW CHECK CASES 

014F 


i 

NEQ 

X,%'A',NOTA 

0157 



WRITE 

<YOU TYPED AN A> 

0173 

C30001 


JMP 

CYCLE 

0176 


NOTA: 

NEQ 

X,%'B' f NOTB 

017E 



WRITE 

<YOU TYPED A B> 

0199 

C30001 


JMP 

CYCLE 

019C 


NOTB: 

NEQ 

X,%'C',NOTC 

01A4 



WRITE 

<YOU TYPED A C> 

01BF 

C30001 


JMP 

CYCLE 

01C2 


NOTC: 

NEQ 

X,%'D',ERROR 

01CA 



WRITE 

<YOU TYPED A D> 

01E5 



WRITE 

<BYE"I> 

01F 7 

C9 


RET 


01F8 


ERROR: 

WRITE 

<NOT AN A, B, C, OR D> 

021A 

C30001 


JMP 

CYCLE 

021D 


/ 

X: 

DS 

1 ;TEMP FOR CHARACTER 

021E 



END 



Listing 9-19a. Sample Program using NCOMPARE Library 
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TEST FOR LOWER CASE ALPHABETIC 


+ 

+ 

+ 

+ 

+ 

+ 

+ 

0133+3A1D02 

+ 

+ 

+ 

+ 

+ 

0009+# 

+ 

+ 

0136+D661 

+ 

+ 

+ 

+ 

0138+DA4F01 

+ 

+ 

+ 

+ 

+ 


X,%'a', f NOTRAN 
NUL 

X, 97 ,NOTRAN 
NUL NOTRAN 
X,97, 


;BRANCH ON FALSE 


TDIG? 


TDIG? 


GEQ 
IF 
LSS 
IF 
GEQ 
ELSE 
TEST? 

IF 
LDA 
ENDIF 
I RPC 
SET 
EXITM 
ENDM 
SET 
EXITM 

IF TDIG? <= 9 

SUI 
ELSE 
LXI 
SUB 
ENDM 
JC 
ENDM 
ELSE 

TEST? X,97 

JNC 

ENDM 

X IS GREATER OR EQUAL TO LOWER CASE A 


X, 97 

NOT NUL * 
X 

?Y,97 
1 &?Y*- 1 0 1 


'g'-'O' 

TDIG? 

97 

H ,97 
M 

NOTRAN 





GTR X f i 

+ 


IF 

NUL NOTRAN 

+ 


LEQ 

X,122, 

+ 


ELSE 


+ 


LOCAL 

GFL 

+ 


TEST? 

X, 122 

+ 


IF 

NOT NUL X 

013B+3A1D02 


LDA 

X 

+ 


ENDIF 


+ 


I RPC 

?Y,122 

+ 

TDIG? 

SET 

1 &?Y 1 - * 0 1 

+ 


EXITM 


+ 


ENDM 


0001+# 

TDIG? 

SET 

'r-'O* 

+ 


EXITM 


+ 


IF 

TDIG? <= 9 

013E+D67A 


SUI 

122 

+ 


ELSE 


+ 


LXI 

H, 122 

+ 


SUB 

M 

+ 


ENDM 



Listing 9-19b. Segment of Listing 9-19a with +M Option 
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0140+DA4701 

JC 

??0003 

0143+3D 

DCR 

A 

0144+D24F01 

JNC 

NOTRAN 

+ 

??0003: 

ENDM 

0147 3A1D02 


LDA 

014A E65F 


ANI 

014C 321D02 


STA 


NOTRAN: 



X 

5FH 

X 


?UPPER CASE 
;BACK TO X 


Listing 9-19b. (continued) 


Given the SIMPIO and NCOMPARE libraries, it is now possible to 
define the first complete control structure, called the WHEN-ENDW 
group. The form of the group is 

WHEN condition 

statement-1 

statement-2 

statement-n 

ENDW 

where condition is a relational expression taking one of the forms 

id,rel,id id,rel,number ,rel,id ,rel,number 

and id is an identifier; rel is a relational operator (LSS, LEQ, 
EQL, NEQ, GEQ, GTR), and number is a literal numeric value. Similar 
in form to the arguments of the individual relational operators of 
the COMPARE library, the last two forms shown above assume the first 
argument is present in the 8080 accumulator. The condition 
following the WHEN is evaluated as a relational expression, 
according to the rules stated with the COMPARE library. If the 
condition produces a true result, then statement-1 through 
statement-n are executed. Otherwise, control transfers to the 
statement following the ENDW. Nested WHEN-ENDW groups are allowed 
when they take the form: 

WHEN . . . 


WHEN . . . 


WHEN . . . 

• • • 

ENDW 


ENDW 


• • • 
ENDW 
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to arbitrary levels, where the ellipses represent interspersed 
statements. Because of the simplified implementation, nested 
parallel WHEN-ENDW groups are disallowed when they take the form: 

WHEN . . . 

WHEN . . . 

ENDW 

WHEN . . . 

ENDW 


ENDW 

The implementation of the WHEN-ENDW group is based upon macros that 
count WHEN-ENDW groups and generate branches and labels at the 
proper levels in the structure. 

Listing 9-20 shows the WHEN macro library, consisting of four 
macros: 


GENWTST (generate WHEN test) 

GENLAB (generate label) 

WHEN (beginning of WHEN group) 

ENDW (end of WHEN group) 

These macros, in turn, use the macros in the NCOMPARE library shown 
previously and thus are assumed to exist in the user's program as a 
result of a MACLIB NCOMPARE statement. Label generation is based on 
the WCNT (WHEN count) and WLEV (WHEN level) counters. WCNT is 
incremented each time a WHEN is encountered, and WLEV keeps track of 
the number of WHENs that have occurred without corresponding ENDWs. 

Upon encountering the first WHEN, the WCNT and WLEV counters 
are set to zero, and the WHEN macro is redefined to generate the 
first WHEN test by invoking GENWTST, using the relation R, operands 
X and Y, and WHEN counter WCNT. The value of WCNT is passed to 
GENWTST rather than the characters WCNT themselves. Thus, at the 
first invocation of GENWTST, the dummy argument NUM has the value 0. 
The first argument to GENWTST, called TST, corresponds to a 
relational operation (LSS through GTR) and thus is invoked 
automatically within the body of GENWTST, using the negated form of 
the relational because the TL argument is empty. 

Again referring to the body of the GENWTST macro in Listing 9— 
20, the last argument, corresponding to the false label of the 
relational operation, is the constructed label ENDW&num, where num 
has the value 0 initially, and successively larger values on later 
invocations. Each time GENWTST is invoked, it generates a 
relational test and a branch on false to a generated label. It is 
the responsibility of the ENDW macro to produce the appropriate 
balanced label when encountered in the program. 
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In the body of the WHEN macro in Listing 9-20, the WLEV level 
counter is set to the current WCNT, and the WCNT is incremented in 
preparation for the next WHEN statement. Similar to nearly all 
macros that redefine themselves, the outer macro definition of WHEN 
invokes the newly created WHEN macro before exit. 

Upon encountering the ENDW statement in the source program, the 
ENDW macro first invokes GENLAB to generate the appropriate ENDW 
label. The first argument to GENLAB is the label prefix ENDW? the 
second argument is the evaluated parameter %WLEV corresponding to 
the current ENDW label. If only one WHEN statement is encountered, 
for example, the value of WLEV is zero, and thus GENLAB produces the 
label ENDWO, which is the destination of the earlier branch 
generated by an invocation of GENWTST. Following the invocation of 
GENLAB, WLEV is decremented to account for the fact that one more 
destination label has been resolved. 


9 

• 

macro 

library for "when" construct 

9 

9 

label 

generators 

genwtst 

macro 

tst,x,y,num 

7 7 

generate a "when" test (negated form), 

7 7 

invoke 

macro "tst" with parameters 

7 7 

x,y with jump to endw & num 


tst 

x,y,,endw&num 


endm 


7 

genlab 

macro 

lab,num 

7 7 

produce the label "lab" & "num" 

lab&num 

: 



endm 


7 

7 

"when" 

macros for start and end 

7 

when 

macro 

xv,rel,yv 

7 7 

initialize counters first time 

went 

set 

0 ??number of whens 

when 

macro 

x,r,y 


genwtst r,x,y,%wcnt 

wlev 

set 

went ?;next endw to generate 

went 

set 

wcnt+1 ?;number of "when"s 


endm 



when 

xv,rel,yv 


endm 


7 

endw 

macro 


7 7 

generate the ending code for a "when" 


genlab 

endw,%wlev 

wlev 

set 

wlev-1 ;?count current level down 


;? wlev must not go below 0 (not checked) 

endm 


Listing 9-20. Macro Library for the WHEN Statement 
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As an example of the use of WHEN-ENDW, Listing 9-21a shows a 
sample program that resembles the previous character scanning 
function, but uses the WHEN group in place of simple tests and 
branches. As before, a single character is read from the console 
and first tested for possible case conversion. The statement WHEN 
X,GEQ,61H causes the three statements that follow to execute only 
when X is greater than or equal to 61H (lower-case a). Further, the 
four WHEN groups that follow test for the specific characters A, B, 
C, or D. If an A is typed, the corresponding WHEN group executes, 
and control transfers back to the CYCLE label where another 
character is read from the console. If the letter D is typed, the 
program responds with two messages and returns to the console 
command processor. 

Listing 9-21b shows the same program with full macro trace 
enabled. This portion of the program shows macro processing for the 
first WHEN-ENDW group only, although the remaining groups are 
processed in a similar fashion. It is a worthwhile exercise to 
determine that the nesting rules for WHEN groups are properly 
stated, and that the restriction on nested parallel groups is 
necessary. 
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0100 


0100 

012B 

0133 

013B 3A1102 
013E E65F 
0140 321102 
0143 


0143 

014B 

0167 C30001 
016A 


ORG 10 OH 

MACLIB SIMPIO ;SIMPLE IO LIBRARY 

MACLIB NCOMPARE;EXPANDED COMPARE OPS 
MACLIB WHEN ;WHEN CONSTRUCT 

? 

CYCLE: WRITE <TYPE A CHARACTER FROM A TO D > 

READ X 

? TEST FOR LOWER CASE ALPHABETIC 

WHEN X,GEQ,61H 

LDA X 

ANI 5FH ?CLEAR LOWER CASE BIT 

STA X ;STORE BACK TO X 

ENDW 

? NOW CHECK CASES 

WHEN X,EQL,%'A' 

WRITE <YOU TYPED AN A> 

JMP CYCLE 

ENDW 


016A 

0172 

018D C30001 
0190 


WHEN X,EQL,%'B' 

WRITE <YOU TYPED A B> 

JMP CYCLE 

ENDW 


0190 

0198 

01B3 C30001 
01B6 


WHEN X,EQL,%'C' 

WRITE <YOU TYPED A C> 

JMP CYCLE 

ENDW 


01B6 


WHEN 

01BE 


WRITE 

01D9 


WRITE 

01EB C9 


RET 

01EC 


ENDW 

01EC 

7 

WRITE 

020E C30001 


JMP 

0211 

/ 

X: 

DS 


X,EQL,% 'D' 

<YOU TYPED A D> 
<BYE~!> 


<NOT AN A, B, C, OR D> 

CYCLE 

1 ;TEMP FOR CHARACTER 


Listing 9-21a. Sample WHEN Program with -M in Effect 
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TEST FOR LOWER CASE ALPHABETIC 



i 

WHEN 

X,GEQ,6lH 

0000+# 

WCNT 

SET 

0 

+ 

WHEN 

MACRO 

X,R,Y 

+ 


GENWTST 

R,X,Y,%WCNT 

+ 

WLEV 

SET 

WCNT 

+ 

WCNT 

SET 

WCNT+1 

+ 


ENDM 


+ 


WHEN 

X f GEQ f 61H 

+ 


GENWTST 

GEQ r X,61H,%WCNT 

+ 


GEQ 

X,61H,,ENDW0 

+ 


IF 

NUL 

+ 


LSS 

X , 61H,ENDW0 

+ 


IF 

NUL ENDWO 

+ 


GEQ 

X , 61H , 

+ 


ELSE 


+ 


TEST? 

X, 61H 

+ 


IF 

NOT NUL X 

0133+3A1102 


LDA 

X 

+ 


ENDIF 


+ 


IRPC 

? Y , 61H 

+ 

TDIG? 

SET 

1 &?Y* - * 0 * 

+ 


EXITM 


+ 


ENDM 


0006+# 

TDIG? 

SET 

'6*-* 0* 

+ 


EXITM 


+ 


IF 

TDIG? <= 9 

0136+D661 


SUI 

61H 

+ 


ELSE 


+ 


LXI 

H , 61H 

+ 


SUB 

M 

+ 


ENDM 


0138+DA4301 


JC 

ENDWO 

+ 


ENDM 


+ 


ELSE 


+ 


TEST? 

X, 61H 

+ 


JNC 


+ 


ENDM 


+ 


ENDM 


0000+# 

WLEV 

SET 

WCNT 

0001+# 

WCNT 

SET 

WCNT+1 

+ 


ENDM 


+ 


ENDM 


013B 3A1102 


LDA 

X 

013E E65F 


ANI 

5FH ? CLEAR 

0140 321102 


STA 

X ;STORE 



ENDW 



i 

• • • 



Listing 9-21b. Partial Listing of Listing 9-21a with +M Option 
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A second control structure, called the DOWHILE-ENDDO group, 
takes the general form: 

DOWHILE condition 
statement-1 
statement-2 
• • • 

statement-n 

ENDDO 

where the condition and nesting rules are identical to the WHEN-ENDW 
group. The DOWHILE group is similar in concept to the WHEN group, 
except that statements 1 through n execute repetitively as long as 
the condition remains true. That is, the condition is evaluated 
when the DOWHILE is encountered in normal program flow. If the 
condition produces a false value, then control transfers to the 
statement following the ENDDO. Otherwise, the statements within the 
group execute until the ENDDO is reached. Upon encountering the 
ENDDO, control transfers back to the DOWHILE, and the condition is 
evaluated again. Iteration continues through the group until the 
condition produces a false value. 

The macro library for the DOWHILE group is shown in Listing 9- 
22. The DOWHILE statement invokes the relational operator macros to 
produce the proper sequence of tests and branches. Upon 
encountering the ENDDO, the proper label and jump sequence is again 
generated. The only essential difference in the DOWHILE and WHEN 
groups is that the location of the DOWHILE test must be labeled, and 
a JMP instruction must be generated to this label at the end of each 
group. 
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; macro library for "dowhile" construct 

7 

gendtst macro tst,x,y,num 
;; generate a "dowhile" test 

tst x,y,,endd&num 

endm 
7 

gendlab macro lab,num 

;; produce the label lab & num 

;; for dowhile entry or exit 

lab&num: 

endm 

7 

gendjmp macro num 

;; generate jump to dowhile test 

jmp dtest&num 

endm 


dowhile macro xv,rel,yv 
;; initialize counter 

docnt set 0 ;number of dowhiles 

7 7 

dowhile macro x,r,y 
;; generate the dowhile entry 

gendlab dtest f %docnt 
;; generate the conditional test 

gendtst r,x f y,%docnt 

dolev set docnt ;;next endd to generate 

docnt set docnt+1 

endm 

dowhile xv,rel,yv 
endm 
7 

enddo macro 

;; generate the jump to the test 

gendjmp %dolev 

;; generate the end of a dowhile 

gendlab endd f %dolev 
dolev set dolev-1 

endm 


Listing 9-22. 


Macro Library for the DOWHILE Statement 
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In Listing 9-22, GENDTST (generate DOWHILE test), GENDLAB 
(generate DOWHILE label), and GENDJMP (generate DOWHILE jump) are 
all label generators used in the macros that follow. Similar to the 
WHEN macro, DOWHILE uses the counters DOCNT and DOLEV to keep track 
of the number of DOWHILE groups encountered along with the current 
DOWHILE level, corresponding to the number of unmatched DOWHILEs. 
The DOWHILE macro first generates the entry label DTESTn, where n is 
the DOWHILE count. The conditional test is then generated, similar 
to the WHEN macro, with a branch on false condition to the ENDDn 
label that is eventually generated by the ENDDO macro. Finally, the 
DOWHILE macro increments the DOCNT counter in preparation for the 
next group. 

The ENDDO macro in Listing 9-22 first generates the JMP 
instruction back to the DOWHILE test, using the GENDLAB utility 
macro, and then produces the ENDDn label that becomes the target of 
the jump on false condition. The form of the expanded macros for 
one nested level thus becomes: 

DTESTO: 

conditional jump to ENDDO 
DTESTl: 

conditional jump to ENDD1 
• • • 

JMP DTESTl 


ENDDl 
JMP DTESTO 

Listing 9-23a shows an example of a program that uses the 
DOWHILE group. Although this program differs slightly from the 
previous examples, the principal function is the same: a STOP 

character is first read from the console, followed by a group of 
statements that repetitively execute in search of the STOP 
character. Two DOWHILE groups occur within the program. The first 
group checks each character typed (X) to see if it matches the STOP 
character. If not (DOWHILE X,NEQ,STOP), the statements up through 
the matching ENDDO are processed. If the value of X is the 
character A, then the message YOU TYPED AN A is sent to the console. 
Otherwise, the message NOT AN A is typed, followed by a check to see 
if the STOP character was typed. If so, the messages STOP CHARACTER 
and BYE! appear at the console. Control continues through the ENDWs 
to the ENDDO and back to the DOWHILE header. The DOWHILE X,NEQ,STOP 
produces a false condition, and control transfers to the XRA A 
instruction following the ENDDO. 
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0100 



ORG 

100H 




MACLIB 

SIMPIO ;SIMPLE IO LIBRARY 




MACLIB 

NCOMPARE;EXPANDED COMPARE OPS 




MACLIB 

WHEN ?WHEN CONSTRUCT 




MACLIB 

DOWHILE ;DOWHILE STATEMENT 

0100 


i 

WRITE 

<TYPE THE STOP CHARACTER: > 

0127 



READ 

STOP 



7 

X = 0 FOR THE FIRST LOOP 

012F 



DOWHILE 

X f NEQ f STOP ;LOOK FOR STOP CHARACTER 

0139 



WRITE 

<TYPE A CHARACTER: > 

0159 



READ 

X 

0161 


7 

WHEN 

X,EQL , % 1 A 1 

0169 



WRITE 

<YOU TYPED AN A> 

0185 



ENDW 


0185 


7 

WHEN 

X,NEQ,% 1 A' 

018D 



WRITE 

<NOT AN A> 

01A3 




WHEN X,EQL,STOP 

01AD 




WRITE <STOP CHARACTER> 

01C9 




WRITE <BYE"!> 

01DB 




ENDW 

01DB 



ENDW 


01DB 



ENDDO 




7 

• 

t 

CLEAR THE SCREEN (23 CRLF'S) 

01DE 

AF 


XRA 

A 

01DF 

320002 


STA 

X ?X=0 

01E2 



DOWHILE 

X,LSS,23 

01EA 



WRITE 

<> 

01F8 

210002 


LXI 

H ,X 

01FB 

34 


INR 

M ?X=X+1 

01FC 



ENDDO 


01FF 

C9 


RET 


0200 

00 

7 

X: 

DB 

0 ;EXECUTES "DOWHILE" FIRST TIME 

0201 


STOP: 

DS 

1 ;STOP CHARACTER 


Listing 9-23a. An Example Using the DOWHILE Statement 
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CLEAR THE SCREEN (23 CRLF'S) 


01DE AF 

XRA 

A 

01DF 320002 

STA 

X ?X=0 


DOWHILE 

X,LSS,23 

01E2+3A0002 

LDA 

X 

01E5+D617 

SUI 

23 

01E7+D2FF01 

JNC 

ENDDl 


WRITE 

<> 

01EA+C3F001 

JMP 

?? 0014 

01ED+0D0A 

??0013: 

DB CR,LF 

01EF+24 

DB 


01F0+0E09 

??0014: 

MVI C,MSGOUT 

OIF2+11ED01 

LXI 

D,??0013 

01F5+CD0500 

CALL 

BDOS 

01F8 210002 

LXI 

H, X 

01FB 34 

INR 

M ?X=X+1 


ENDDO 


01FC+C3E201 

JMP 

DTEST1 

01FF C9 

RET 



Listing 9-23b. Partial Listing of Listing 9-23a 
with Macro Generation 


In Listing 9-23a, the second DOWHILE-ENDDO group clears the 
normal CRT screen size of 23 lines. This is accomplished by first 
setting X to the value zero, followed by a DOWHILE group that checks 
the condition X,LSS,23 which iterates until X reaches the value 23. 
The WRITE statement within the DOWHILE group produces only the 
carriage return line-feed on each iteration because the character 
sequence within the brackets is empty. Following the WRITE 
statement, X is incremented by one, acting as a line counter. When 
X reaches 23, the RET statement following the matching ENDDO 
receives control, and the program terminates by returning to the 
console processor. Note that the DB statement for X provides the 
initial value zero, so that the first DOWHILE executes at least one 
time. 


Listing 9-23b shows a portion of the program of Listing 9-23a, 
with partial macro trace enabled. This trace does not show the 
generated labels ENDDl and DTEST1 because no machine code was 
generated on those lines. The +M assembly parameter would show the 
labels, however. The locations of these labels can be derived from 
the hex listing to the left; the JNC ENDDl produces the destination 
address 01FF corresponding to the RET statement, and the JMP DTEST1 
produces the address 01E2 corresponding to the LDA X instruction at 
the beginning of the DOWHILE group. 

The last control structure presented in this section is the 
SELECT-ENDSEL group, which corresponds to the FORTRAN computed GO¬ 
TO, the ALGOL switch statement, and the PL/M case statement. The 
general form of the SELECT group is 
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SELECT id 

statement-set-0 

SELNEXT 

statement-set-1 

SELNEXT 

SELNEXT 

statement-set-n 

ENDSEL 

where id is a data label corresponding to an 8-bit value in memory, 
and statement set 0 through n denotes groups of statements separated 
by SELNEXT delimiters. 

The action of the SELECT-ENDSEL group is as follows: the 

variable given in the SELECT statement is taken as a case number 
assumed to be in the range 0 through n. If the value is 0, 
statement-set-0 is executed and, upon completion of the group, 
control transfers to the statement following the ENDSEL. If the 
variable has the value 1, then statement-set-1 executes. Similarly, 
if the variable produces a value i between 0 and n, then statement- 
set-i receives control. There can be up to 255 groups of statements 
within each SELECT-ENDSEL group, and any number of distinct SELECT- 
ENDSEL groups. Nested SELECT-ENDSEL groups are not allowed. That 
is, a SELECT-ENDSEL group cannot occur within a statement-set that 
is enclosed in another SELECT-ENDSEL group. As a convenience, the 
variable following the SELECT can be omitted, in which case the 
current 8080 accumulator content selects the proper case. 

Listings 9-24a and 9-24b show the SELECT macro library that 
implements the SELECT-ENDSEL group. The general strategy is to 
count the cases as they occur, starting with the SELECT, delimited 
by NEXTSEL, and terminated by ENDSEL. As the cases occur, a case 
label is generated that takes the form CASEn@m where n counts the 
SELECT-ENDSEL groups, and m is the case number within group n. A 
jump instruction is generated at the end of each case to the label 
ENDSn that marks the end of the SELECT group number n. Upon 
encountering the end of the group, a select-vector is generated that 
contains the address of each case within the group, headed by the 
label SELVn, where n is again the group number. Machine code is 
thus generated at the SELECT entry, which indexes into the select 
vector, based upon the SELECT variable, to obtain the proper case 
address. The first statement within the case receives control based 
upon the value obtained from this vector. 

The general form of the machine code generated for the first 
SELECT group within a program (group n = 0) is: 
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LDA id 

LXI SELVO 

(index HL by id, and 
load the address to HL) 
PCHL 
CASEO0O: 

statement-set-0 
JMP ENDSO 

CASEO01: 

statement-set-1 
JMP ENDSO 

CASE@n: 

statement-set-n 


JMP 

ENDSO 

SELVO: 


DW 

CASEO0O 

DW 

CASE0@1 

DW 

CASE0@n 

ENDSO: 



Listing 9-24a contains the label generators GENSLXI (generate 
SELECT LXI), GENCASE (generate case labels), GENELT (generate select 
vector element), and GENSLAB (generate SELECT label). Listing 9-24b 
contains the macro definitions for SELNEXT (select next case), 
SELECT, and ENDSEL. 

In Listing 9-24b, the SELECT macro begins by zeroing CCNT which 
counts SELECT-ENDSEL groups and then redefines itself, similar to 
the WHEN and DOWHILE macros. The redefined SELECT macro then 
generates the select vector indexing operation by loading the 
indexing variable, if necessary, and then fetches the specific case 
address. No machine code is generated to check that the indexing 
variable is within the proper range. The PCHL at the end of this 
code sequence performs the branch to the selected case. 

At the end of the redefined select macro, SELNEXT is invoked 
automatically, to delimit the first case in the SELECT group 
(otherwise SELECT would have to be followed immediately by SELNEXT 
in the user program to generate the proper labels). SELECT also 
zeros the ECNT variable, which counts the cases until ENDSEL is 
encountered. 
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; macro library for "select" construct 

} 

; label generators 

genslxi macro num 

;; load hi with address of case list 

lxi h,selv&num 

endm 

; 

gencase macro nura,elt 
;; generate jmp to end of cases 

if elt gt 0 

jmp ends&num ;;past addr list 

endif 

;; generate label for this case 

case&num&@&elt: 
endm 


genelt macro num,elt 

;; generate one element of case list 

dw case&num&@&elt 

endm 


genslab macro num,elts 
;; generate case list 

selv&num: 

ecnt set 0 ;;count elements 

rept elts ;;generate dw's 
genelt num,%ecnt 
ecnt set ecnt+1 

endm ;;end of dw's 

;; generate end of case list label 

ends&num: 

endm 

Listing 9-24a. Macro Library for SELECT Statement 
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selnext macro 


7 7 

generate the next case 


gencase 

%ccnt, 

%ecnt 

7 7 

increment the 

case element count 

ecnt 

set 

ecnt+1 



endm 




7 

select 

macro 

var 



7 7 

generate case 

selection code 

cent 

set 

0 


?;count "selects" 

select 

macro 

V 

1 

^redefinition of select 

7 7 

select 

on v or 

accumulator contents 


if 

not nul v 


Ida 

V 

i 

?;load select variable 


endif 





genslxi 

%ccnt 


;generate the lxi h,selv# 


mov 

e,a 


jereate double precision 


mvi 

d,0 


?v in d,e pair 


dad 

d 


;single prec index 


dad 

d 


;double prec index 


mov 

e,m 


;low order branch addr 


inx 

h 


7 to high order byte 


mov 

d,m 


?high order branch index 


xchg 



7 ready branch address in hi 


pehl 


;;gone to the proper case 

ecnt 

set 

0 

) 

;7 element counter reset 


endm 




7 7 

invoke : 

redefined 

select the first time 


select 

var 




selnext 


J 

^automatically select case i 


endm 




7 

endsel 

macro 




7 7 

end of i 

select, 

generate case list 


gencase 

%ccnt, 

%ecnt ;;last case 


genslab 

%ccnt, 

%ecnt ;;case list 

7 7 

increment "select" count 

cent 

set 

ccnt+1 




endm 







Listing 9-24b. Library for SELECT Statement (continued) 
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You use SELNEXT, shown at the top of Listing 9-24b, to delimit 
cases. The GENCASE utility macro is invoked which, in turn, 
generates a JMP instruction for the previous group, if this is not 
group zero, and then produces the appropriate case entry label. 
SELNEXT also increments the select element counter ECNT to account 
for yet another case. 

Upon encountering the ENDSEL, the last macro in Listing 9-24b, 
GENCASE is again called to generate the JMP instruction for the last 
case. GENSLAB then produces the select vector by first generating 
the SELVn label, followed by a list of ECNT DW statements that have 
the case label addresses as operands. 

Listing 9-25a gives an example of a simple program that uses 
two SELECT groups. The first SELECT group executes one of five 
different MVI instructions based on the value of X. The second 
SELECT group assumes that the 8080 accumulator contains the selector 
index and executes one of three different MVI instructions. The 
program of Listing 9-25a illustrates generated control structures, 
and does not produce any useful values as output. The sorted Symbol 
Table shown at the end of the listing gives the generated label 
addresses for the individual cases. 

Listing 9-25b shows a segment of the previous program with 
generated macro lines. Note the case selection code following 
SELECT X at the end of the listing. 

Listing 9-25c gives a more complete trace of the SELECT-ENDSEL 
group, showing the actions of the macros as they expand for the 
second SELECT-ENDSEL group of Listing 9-25a. The listing has been 
edited to remove the case selection code, which is listed in Listing 
9-25b, and the code generated for case number 2. Cross-reference 
Listing 9-25c with the SELECT macro library given in Listings 9-24a 
and 9-24b if you are confused about the actions of these macros. 
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MACLIB 

SELECT 

0000 



SELECT 

X 

0010 

3E00 


MV I 

A,0 

0012 



SELNEXT 


0015 

3E01 


MV I 

A,1 

0017 



SELNEXT 


001A 

3E02 


MV I 

A,2 

001C 



SELNEXT 


00 IF 

3E03 


MV I 

A,3 

0021 



SELNEXT 


0024 

3E04 


MV I 

A,4 

0026 



ENDSEL 


0033 


? 

SELECT 


0040 

0600 


MV I 

B, 0 

0042 



SELNEXT 


0045 

0601 


MV I 

B,1 

0047 



SELNEXT 


004A 

0602 


MV I 

B, 2 

004C 



ENDSEL 


0055 


r 

X: 

DS 

1 


0010 

CASE0@0 

0015 

CASE0@1 

001A 

CASEO02 

00 IF 

CASE0@3 

0024 

0029 

CASEO05 

0040 

CASE1@0 

0045 

CASE1@1 

004A 

CASE102 

004F 

0033 

ENDS0 

0055 

ENDS1 

0029 

SELV0 

004F 

SELVl 

0055 


CASE0@4 
CASE1@3 
X 


Listing 9-25a. Sample Program Using SELECT with -M +S Options 
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0000+3A5500 

0003+212900 

0006+5F 

0007+1600 

0009+19 

000A+19 

000B+5E 

000C+23 

000D+56 

000E+EB 

000F+E9 

0010 3E00 

0012+C33300 
0015 3E01 

0017+C33300 
001A 3E02 

001C+C33300 
00IF 3E03 

0021+C33300 
0024 3E04 

0026+C33300 

0029+1000 

002B+1500 

002D+1A00 

002F+1F00 

0031+2400 

Listing 9 


All Information 


MACLIB SELECT 
SELECT X 
LDA X 

LXI H,SELV0 

MOV E,A 

MVI D,0 

DAD D 

DAD D 

MOV E ,M 

INX H 

MOV D,M 

XCHG 
PCHL 

MV I A, 0 

SELNEXT 

JMP ENDS0 

MVI A,1 

SELNEXT 

JMP ENDS0 

MV I A f 2 

SELNEXT 

JMP ENDS0 

MV I A, 3 

SELNEXT 

JMP ENDS0 

MV I A f 4 

ENDSEL 

JMP ENDS0 

DW CASE0@0 

DW CASE0@1 

DW CASE0@2 

DW CASEO03 

DW CASEO04 

25b. Segment of Listing 9-25a with Mnemonics 
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SELECT 


+ 

IF 

NOT NUL 

+ 

LDA 


+ 

ENDIF 


+ 

GENSLXI 

%CCNT 

0033+214F00 

LXI 

H,SELV1 

+ 

ENDM 



• • • 

(indexing code 

similar to F 

0000+# 

ECNT SET 

0 

+ 

GENCASE 

%CCNT,%ECNT 

+ 

IF 

0 GT 0 

+ 

JMP 

ENDS1 

+ 

ENDIF 


+ 

CASE1@0: 


+ 

ENDM 


0001+# 

ECNT SET 

ECNT+1 

+ 

ENDM 


+ 

ENDM 


0040 0600 

MV I 

B, 0 


SELNEXT 


+ 

GENCASE 

%CCNT,%ECNT 

+ 

IF 

1 GT 0 

0042+C35500 

JMP 

ENDS1 

+ 

ENDIF 


+ 

CASE101: 


+ 

ENDM 


0002+# 

ECNT SET 

ECNT+1 

+ 

ENDM 



(remaining cases are similar) 




ENDSEL 


+ 


GENSLAB 

%CCNT,%ECNT 

+ 

SELVl: 



0000+# 

ECNT 

SET 

0 

+ 


REPT 

3 

+ 


GENELT 

1,%ECNT 

+ 

ECNT 

SET 

ECNT+1 

+ 


ENDM 


+ 


GENELT 

1,%ECNT 

004F+4000 


DW 

CASE1@0 

+ 


ENDM 


0001+# 

ECNT 

SET 

ECNT+1 

+ 


GENELT 

1 f %ECNT 

0051+4500 


DW 

CASE101 

+ 


ENDM 


0002+# 

ECNT 

SET 

ECNT+1 

+ 


GENELT 

1,%ECNT 

0053+4A00 


DW 

CASE1@2 

+ 


ENDM 



Listing 9-25c. Segment of Listing 9-25a with +M Option 
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0003+# 

ECNT 

SET 

ECNT+1 

+ 


ENDM 


+ 

ENDS1: 



+ 


ENDM 


0002+# 

CCNT 

SET 

CCNT+1 

+ 


ENDM 



Listing 9-25c. (continued) 


It is now possible to show a complete program that uses the 
WHEN, DOWHILE, and SELECT groups. Listing 9-26 shows a program 
similar in function to a more complicated program that interacts 
with the console in executing single-character input commands. The 
two CP/M programs ED and DDT both take this general form. (See the 
CP/M documentation for details.) A single letter selects a single 
action that might correspond to an edit request in the ED program or 
a debug request in DDT. Upon completion of each command, control 
returns to the main loop to accept another single-letter command. 

The program given in Listing 9-26 begins by loading the macro 
definitions for the SIMPIO, NCOMPARE, WHEN, DOWHILE, and SELECT 
operations. Several messages are then sent to the console device, 
followed by a single DOWHILE-ENDDO group that encompasses nearly the 
entire program. The DOWHILE group is controlled by the X,NEW,%'D' 
test and thus continues to loop while the X character is not the 
letter D. On each iteration of the DOWHILE group, a single letter 
is read from the console and converted to upper-case, if necessary. 
To ensure that the letter is in the proper range of values, two WHEN 
groups follow that convert illegal values to the letter E, which 
subsequently produces an error response. 

Following the WHEN tests in Listing 9-26, the character must be 
in the range A through E. Before indexing into the SELECT group, 
this value is normalized to the absolute value 0 through 4, 
corresponding to each of the possible values. The SELECT statement 
uses the value in the accumulator to select one of the five cases, 
producing the appropriate response to the letters A through D, or an 
error response for the last case. Upon completion of the SELECT 
group, control returns to the DOWHILE where the last character typed 
is tested against the letter D. If X is not equal to the letter D, 
the iteration continues. Otherwise, the DOWHILE completes and 
control returns to the console processor. 

The control structures presented in this section are 
representative of the forms that can be implemented. Additional 
facilities, such as the controlled iteration found in FORTRAN DO 
loops or ALGOL FOR loops can be implemented using essentially the 
same techniques used for the WHEN and DOWHILE. Further, subroutine 
parameters can also be defined with macro libraries. It is 
relatively easy to include control substructures for the stack 
machine given in the previous section, allowing machine independent 
programming of control structures and arithmetic operations. 
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0100 


ORG 100H ;BEGINNING OF TPA 



MACLIB SIMPIO ?SIMPLE READ/WRITE 



MACLIB NCOMPARE;COMPARISON OPS 



MACLIB WHEN ;"WHEN" CONSTRUCT 



MACLIB DOWHILE ;"DOWHILE" CONSTRUCT 



MACLIB SELECT ;"SELECT" CONSTRUCT 


? 

7 

USING THE CCP'S STACK, READ INPUT 


7 

CHARACTERS, UNTIL A Z IS TYPED 

0100 


WRITE <SAMPLE CONTROL STRUCTURES> 

0127 


WRITE <TYPED SINGLE CHARACTERS FROM> 

0150 


WRITE <A TO D, I^'^'LL STOP ON D> 

0174 

$ 

DOWHILE X,NEQ,%'D' 

017C 


WRITE <TYPE A CHARACTER: > 

019C 


READ X 

01A4 


WHEN X,GEQ,%'A' 

01AC 3ABF02E65F 

LDA X! ANI 05FH! STA X ;CONV CASE 

01B4 


ENDW 

01B4 


WHEN X,LSS,%'A' 

01BC 3E4532BF02 

MVI A,'E' ! STA X ? SET TO ERROR 

01C1 


ENDW 

01C1 


WHEN X,GTR,%'E' 

01CC 3E4532BF02 

MVI A,'E'! STA X ;SET TO ERROR 

01D1 


ENDW 

01D1 3ABF02D641 

LDA X! SUI 'A' ;NORMALIZE TO 0-4 

01D6 


SELECT ?BASED ON X IN ACCUM 

01E3 


WRITE <YOU SELECTED CASE A> 

0204 


SELNEXT 

0207 


WRITE <YOU SELECTED CASE B> 

0228 


SELNEXT 

022B 


WRITE <YOU SELECTED CASE C> 

024C 


SELNEXT 

024F 


WRITE <YOU SELECTED CASE D> 

0270 


WRITE <SO I' 1 M GOING BACK~!> 

0290 


SELNEXT 

0293 


WRITE <BAD CHARACTER> 

02AE 


ENDSEL 

02BB 


ENDDO 

02BE C9 


RET 7BACK TO CCP 


• 

DATA AREA 

02BF 00 

X: 

DB 0 ? X=00 INITIALLY 


Listing 9-26. Program Using WHEN, DOWHILE, and SELECT 
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9.4 Operating System Interface 

In a general purpose computing environment, macros often 
provide systematic and simplified mechanisms for programmatic access 
to ooerating system functions. Throughout this manual, the examples 
have shown various low-level calls to the CP/M operating system that 
implement functions such as single-character input, single-character 
output, and full message output. In each case, the macros simplify 
the operations by performing the low-level register setups and calls 
that perform the function. 

This section introduces more comprehensive operating system 
interface macros and shows a sample macro library that allows 
simplified disk file operations for sequential stream input/output 
operations. The principal macros of this library that allow file 
access are listed below: 


FILE 

GET 

PUT 

FINIS 

ERASE 

DIRECT 

RENAME 


set up a named file for subsequent disk operations. 

read a single character from specific data source. 

send a character to a specific data destination. 

terminate file access for specific group of files. 

remove a specific disk file. 

search for a specific file on the disk. 

rename a specific disk file. 


Before introducing the macro library that performs these functions, 
the operation of each macro is described, followed by a simple 
example. 

The FILE operation takes the form: 

FILE mode, file id, diskname,filename,filetype,buffsize,buffadr 

where the individual parameters of the FILE macro describe a file to 
be accessed in the program. The parameter values for the FILE macro 
are: 


mode INFILE (input file) 

OUTFILE (output file) 

SETFILE (set up filename Eor ancillary functions) 

fileid file identifier for internal reference throughout the 
program. 
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diskname disk drive name (A, B,. . .) containing the file 

being accessed, or empty if the default drive is 
being used. 

filename the filename (up to eight characters) of the disk 
file being accessed; if "1” or ”2" is specified, 
then the first or second default filename is used, 
respectively. 

filetype the filetype (up to three characters) of the file 
being accessed; if "l” or "2" has been specified for 
the filename parameter and an empty filetype is 
given, then the filetype is taken from the selected 
default filename; otherwise, the filetype is set to 
blanks. 


buffsize the size in bytes of the buffer area used for this 
file; the value is rounded down to an integral 
multiple of the disk sector size; if the rounding 
produces a result that is too small, or if the 
parameter is empty, then only one sector is 
buffered. 


buffaddr the address of the buffer area to use during accesses 
to this file; if empty, then the buffer address is 
assigned automatically. 


For example, the FILE statement 

FILE INFILE,ZOT,A,NAMES,DAT 

sets up the file NAMES.DAT on disk drive A for subsequent access. 
Internal to the program, this file is referenced by the name ZOT. 
Further, the buffer address is assigned automatically, and the 
buffer size is set to one sector (usually 128 bytes). Larger 
buffers are useful in minimizing rotational delay on the disk due to 
missed sectors during the file operations. If the NAMES.DAT file 
does not exist, an error message is sent to the console, and the 
program aborts. For example, an output file can be created using 
the statement: 

FILE OUTFILE,ZAP,B,ADDRESS,DAT,1000 

which creates the file ADDRESS.DAT on drive B for subsequent output, 
referenced internally by the name ZAP. In this case, the buffer 
size is set to 1000 bytes (rounded down to 7 * 128 = 896 bytes) , and 
the base address of the buffer is set automatically. The sample 
programs show alternative FILE options. 

The GET macro invocation takes the form: 

GET device 
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where device specifies a simple peripheral or a disk file defined by 
a previously executed FILE statement. The GET statement reads one 
byte of data into the 8080 accumulator from the specified device. 
The possible device names ares 


KEY console keyboard input 

RDR reader device 

fileid previously defined file identifier given in a FILE 

statement 


The following GET invocations perform the functions shown to the 
right below. 


GET KEY read one keyboard character. 

GET RDR read one reader character. (See the CP/M 
documentation for READER entry point definition.) 

GET ZOT read one character from the file given by the 
internal name ZOT. (The NAMES.DAT file if the 
above FILE statement had been executed.) 


The end-of-data can be detected in two ways: if the file contains 
character data, the end-of-file is detected by comparing the 
individual characters with the standard CP/M end-of-file mark, which 
is a CTRL-Z (hexadecimal 1AH). The GET function also returns with 
the 8080 zero flag set to true if a real end-of-file is encountered, 
so that pure binary files can be read to the end-of-data. 

The PUT macro performs the opposite function from the GET 
macro. The PUT invocation takes the form: 

PUT device 

where device specifies a simple output peripheral or a disk file 
defined previously using the FILE macro. The possible device names 
are 


CON 

PUN 

LST 

fileid 


console display device 
system punch device 
system listing device 

previously defined output file identifier 
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These PUT invocations perform the following functions: 


PUT 

CON 

write 

the 

accumulator 

character 

to 

the 

console. 

PUT 

PUN 

write 

the 

accumulator 

character 

to 

the 

punch. 

PUT 

LST 

write 

the 

accumulator 

character 

to 

the 

list device. 

PUT 

ZAP 

write 

the 

accumulator 

character 

to the file with the 


internal name ZAP. (The ADDRESS.DAT file in the 
preceding example.) 


Note that the character in the accumulator is preserved during the 
invocation, so that it can be involved in further tests or macro 
invocations following the PUT statement. 

The FINIS statement closes a file or set of files upon 
completion of file access. In the case of an output file, the 
internal buffers are written to disk, and the filename is 
permanently recorded on the disk for future access. The form of the 
FINIS invocation takes the form: 

FINIS filelist 

where filelist is a single internal name that appeared previously in 
a file statement or a list of such filenames, enclosed within angle 
brackets and separated by commas. Although it is not necessary to 
close input files with the FINIS statement, it is good practice, 
because the file close operation might be required on future 
versions of the macro library. An example of the FINIS statement 
is: 


FINIS ZAP write all buffers for the ZAP file, and record 

the file in the disk directory? in the above 
example, the ADDRESS.DAT file is closed. 

The ERASE macro allows programmatic removal of a disk file 
given by the specified file identifier defined in a previous FILE 
statement. If the file identifier is not used in a GET or PUT 
statement, then the FILE statement can have the mode SETFILE. This 
mode requires less program space than an INFILE or OUTFILE 
parameter. Examples of the ERASE statement are given later in this 
section. In the example 

ERASE ZOT 

however, the file NAMES.DAT is removed from the disk, given the 
previous FILE statement that defines ZOT. 

The DIRECT macro searches for a specific file on the disk. 
Similar to the ERASE macro, the file identifier must be previously 
given in a FILE statement using one of the three possible file 
modes. The DIRECT invocation sets the 8080 zero flag to false if 
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the file is present on the disk. In both the ERASE and DIRECT 
macros, the file ideijtifiers can reference filenames and types with 
embedded ? characters, similar to the normal CP/M DIR command, where 
the question mark matches any character in the filenames being 
scanned. The macro invocation 

DIRECT ZAP 

for example, returns with the zero flag cleared if the file 
ADDRESS.DAT is present, and with the zero flag set if the file is 
not present, given the original FILE statement involving the ZAP 
file identifier. 

The RENAME macro takes the form: 

RENAME newfile,oldfile 

where newfile and oldfile are file identifiers that have appeared in 
previous FILE statements. The RENAME macro changes the filename 
given by oldfile to the filename given to newfile. The file 
identifiers newfile and oldfile must appear in previously executed 
FILE statements, but can have a mode of SETFILE if they are not used 
in GET or PUT macros. If the drive names for oldfile and newfile 
differ, then the drive name of newfile is assumed. The sequence of 
macro invocations 

FINIS ZAP ;CLOSE ZAP 

ERASE ZOT ?REMOVE ZOT 

RENAME ZOT,ZAP ;CHANGE NAMES 

for example, first closes the ADDRESS.DAT file on drive B, then 
erases the NAMES.DAT file on drive A. The RENAME macro then changes 
the ADDRESS.DAT file to the name NAMES.DAT file on drive A. 

Listing 9-27 shows the use of the FILE, GET, PUT, and FINIS 
macros in a working program. This program reads an input file, 
specified at the Console Command Processor level as the first 
filename, and translates each lower-case alphabetic character to 
upper-case. The output is sent to the file given as the second 
parameter at the command level. For a program assembled, loaded, 
and stored as CASE.COM on the disk, a typical execution would be 

CASE L0WER.DAT UPPER.DAT 

This causes the CASE.COM file to load and execute in the Transient 
Program Area. Before execution, the Console Command Processor 
passes LOWER.DAT as the first default filename, and UPPER.DAT as the 
second filename. (See the CP/M documentation for exact details.) 

In Listing 9-27, the CASE program begins by initializing the 
stack pointer to a local stack area in preparation for subsequent 
subroutine calls that occur within the various macros in the SEQIO 
macro library. The first default file specification is then taken 
as the SOURCE file, as defined in the first FILE macro. The second 
FILE statement assigns the second default file specification as an 
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output file with the internal name DEST. In both cases, the FILE 
statements open the respective files and initialize the buffer 
areas, consisting of 2000 bytes rounded down to a multiple of the 
sector size. 

Note that if the UPPER.DAT file already exists, the second file 
statement removes the existing file and creates a new UPPER.DAT file 
before continuing. In either case, the appropriate error messages 
appear at the console if the files cannot be accessed or created in 
the FILE statements. 
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0100 ORG 100H 

; COPY FILE 1 TO FILE 2, CONVERT 

; TO UPPER CASE DURING THE COPY 

; AND ECHO TRANSACTION TO CONSOLE 





MACLIB 

SEQIO 

;SEQUENTIAL I/O LIB 

0000 = 

BOOT 

EQU 

0000H 

;SYSTEM REBOOT 

005F » 

UCASE 

EQU 

5FH 

;UPPER CASE BITS 

0100 317003 



LXI 

SP,STACK 




DEFINE 

SOURCE FILE: 





INFILE 

= INPUT FILE 





SOURCE 

= INTERNAL NAME 





(NUL) 

= DEFAULT DISK 





1 

= FIRST DEFAULT NAME 





(NUL) 

= FIRST DEFAULT TYPE 





2000 

= BUFFER SIZE 

0103 



FILE 

INFILE,SOURCE,,1,,2000 




DEFINE 

DESTINATION FILE: 





OUTFILE 

= OUTPUT FILE 





DEST 

= INTERNAL NAME 





(NUL) 

= DEFAULT DISK 





2 

= SECOND DEFAULT NAME 





(NUL) 

= SECOND DEFAULT TYPE 





2000 

= BUFFER SIZE 

01EC 



FILE 

OUTFILE, 

DEST,,2,,2000 


] 

r 

I 

READ SOURCE FILE 

1, TRANSLATE, WRITE DEST 

02EA 

CYCLE: 

GET 

SOURCE 


02ED FE1A 



CPI 

EOF 

;END OF FILE? 

02EF CA0C03 



JZ 

ENDCOPY 

;SKIP TO END IF SO 


] 

] 

r 

f 

NOT END OF FILE, 

CONVERT TO UPPER CASE 

02F2 FE61 



CPI 

'a' 

;BELOW LOWER CASE "A"? 

02F4 DAFE02 



JC 

NOCONV 

;SKIP IF SO 

02F7 FE7B 



CPI 

'z'+l 

;BELOW LOWER CASE n Z"? 

02F9 D2FE02 



JNC 

NOCONV 

;SKIP IF ABOVE 


1 

r 

MASK OUT LOWER CASE ALPHA BITS 

02FC E65F 



AN I 

UCASE 


02FE 

NOCONV 

s 

PUT 

CON ;WRITE TO CONSOLE 

0306 



PUT 

DEST 

;AND TO DESTINATION FILE 

0309 C3EA02 



JMP 

CYCLE 

;FOR ANOTHER CHARACTER 


ENDCOPY: 



030C 



FINIS 

DEST 

;END OF OUTPUT 

034D C30000 



JMP 

BOOT 

;BACK TO CCP 

0350 


r 

DS 

32 

;16 LEVEL STACK 


STACK: 





BUFFERS: 



1270 = 

MEMSIZE 

EQU 

BUFFERS+0NXTB ;PROGRAM 1 

0370 



END 



Listing 

( 

9-27. 

Lower- 

to Upper- 

■case Conversion Program 
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The CASE program main loop is shown in Listing 9-27 between the 
CYCLE and ENDCOPY labels. Each successive character is read from 
the SOURCE file (in this case, LOWER.DAT) and tested to see if the 
character is in the range of a lower-case a to lower-case z. If in 
this range, the character is changed to upper-case. At the NOCONV 
label, the (possibly translated) character in the accumulator is 
sent to the console device using the PUT CON macro and then sent to 
the DEST file (in this case, UPPER.DAT) . Looping continues back to 
the CYCLE label where another character is read and translated. 

Because the data file is assumed to consist of a stream of 
ASCII characters, the end-of-file is detected when a CTRL-Z is 
encountered. When this character is found, control transfers to the 
label ENDCOPY where the DEST file is closed using the FINIS macro. 
An error in writing or closing the DEST file produces an error 
message at the console, and the program aborts immediately. Upon 
completion of the program, control returns to the console processor 
through a system reboot (JMP BOOT). 

The SEQIO library macros assume that all file buffers are 
located at the end of the user's program, as shown in Listing 9-27. 
In particular, the label BUFFERS must appear as the last label in 
the user's program, and becomes the base of the buffers allocated 
automatically in the FILE statements. The actual memory 
requirements for the program can be determined using an EQU as shown 
in Listing 9-27, with a statement of the form: 

MEMSIZE EQU BUFFERS+0NXTB 

that produces the equated value 1270H at the left of the listing. 
In this case, the program does not use the memory area beyond 1270H. 

The macro library for SEQIO is shown in Listing 9-28. This 
listing is the most comprehensive macro library shown in this 
manual, containing an instance of nearly every macro facility 
available in MAC. The following discussion of SEQIO outlines the 
general functions of each macro, but it is left to you to 
investigate the exact operation of the library. 

The SEQIO library begins with generally useful equates and 
utility macros. The label FILERR at the beginning becomes the 
destination of transfers upon encountering a file operation error. 
Because this is a SET statement, it can be changed in the user's 
program to trap error conditions rather than rebooting. The use of 
FILERR is apparent throughout the macro library. 
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sequential file i/o library 


filerr 

set 

OOOOh 

;reboot after error 

@bdos 

equ 

0005h 

;bdos entry point 

@tfcb 

equ 

005ch 

;default file control block 

@tbuf 

equ 

0080h 

;default buffer address 

7 

7 

bdos 

functions 


@msg 

equ 

9 

;send message 

@opn 

equ 

15 

;file open 

@cls 

equ 

16 

;file close 

@dir 

equ 

17 

;directory search 

@del 

equ 

19 

;file delete 

@frd 

equ 

20 

;file read operation 

@fwr 

equ 

21 

;file write operation 

@mak 

equ 

22 

;file make 

@ren 

equ 

23 

;file rename 

@dma 

equ 

26 

;set dma address 

7 

@sect 

equ 

128 

;sector size 

eof 

equ 

lah 

;end of file 

cr 

equ 

Odh 

;carriage return 

If 

equ 

Oah 

;line feed 

tab 

equ 

09h 

horizontal tab 

7 

@key 

equ 

1 

;keyboard 

@con 

equ 

2 

;console display 

@rdr 

equ 

3 

;reader 

@pun 

equ 

4 

;punch 

@ 1st 

equ 

5 

;list device 

7 

7 

keywords for " 

file" macro 

infile 

equ 

1 

;input file 

outfile 

equ 

2 ;outputfile 

setfile 

equ 

3 ;setup name only 

/ 

7 

the 

following 

macros define simple sequential 

7 

file 

operations: 

/ 

fillnam 

macro 

fc,c 

7 7 

fill 

the file 

name/type given by fc for c character: 

@cnt 

set 

c 

;;max length 


irpc 

?fc,fc 

;;fill each character 

7 7 

may 

be end of 

count or nul name 


if 

@cnt=0 

or nul ?fc 


exitra 



endif 



db 

1 &?FC' 

;;fill one more 

@cnt 

set 

@cnt-l 

;;decrement max length 


endm 


;;of irpc ?fc 


Listing 9-28. Sequential Pile Input/Output Library 


All Information Presented Here is Proprietary to Digital Research 


170 




Programmer's Utilities Guide 


9.4 Operating System Interface 


7 7 

7 7 

pad remainder 


rept 

@cnt ??@cnt is remainder 


db 

' ' 77 pad one more blank 


endm 

?;of rept 


endm 


filldef 

macro fcb,?fl,?ln 

7 7 

fill 

the file name from the default fcb 

7 7 

for length ?ln (9 or 12) 


local 

psub 


jmp 

psub ;;jump past the subroutine 

@def: 

77 this subroutine fills from the tfcb (+16) 


mov 

a,m 7 ?get next character to a 


stax 

d ;;store to fcb area 


inx 

h 


inx 

d 


dcr 

c ?;count length down to 0 


jnz 

@def 


ret 


7 7 

end of fill subroutine 

psub: 



filldef 

macro ?fcb,?f,?l 


lxi 

h,@tfcb+?f ;;either @tfcb or @tfcb+16 


lxi 

d, ?fcb 


mvi 

c,?l ;;length = 9,12 


call 

@def 


endm 



filldef fcb,?f1,?ln 


endm 


fillnxt 

macro 

7 7 

initialize buffer and device numbers 

@nxtb 

set 

0 ;;next buffer location 

@nxtd 

set 

@lst+l ?;next device number 

fillnxt 

macro 


endm 



endm 


fillfcb 

macro fid,dn,fn,ft,bs,ba 

7 7 

fill 

the file control block with disk name 

7 7 

fid is an internal name for the file. 

7 7 

dn is 

the drive name (a,b..), or blank 

7 7 

fn is 

the file name, or blank 

7 7 

ft is 

the file type 

7 7 

bs is 

the buffer size 

7 7 

ba is 

the buffer address 


local 

pfcb 

7 7 

7 7 

set up the file control block for the file 

7 7 

look j 

for file name = 1 or 2 

@C 

set 

1 ;jassume true to begin with 


irpc 

?c,fn ;;look through characters of name 


if 

not ('&?C' = '1' or '&?C' = '2') 

@c 

set 

0 ;;clear if not 1 or 2 


endm 



Listing 9-28. (continued) 
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@c is true if fn 



if 

@c ; 

7 7 

fill from default 


if 

nul ft ? 

@c 

set 

else 

12 

@c 

set 

endif 

9 


filldef 

fcb&fid,( 


jmp 

pfcb ; 


ds 

@c ? 


fillnam 

else 

ft,12-@c 


jmp 

pfcb ; 


if 

nul dn 


db 

else 

0 


db 

endif 

'&DN'- * A' 


fillnam 

fn, 8 


;; now generate the 

fillnam ft,3 
end if 

fcb&fid equ 

db 0 

now define the 3 
ds 20 


= 1 or 2 at this point 
;then fn = 1 or 2 
area 

;type specified? 

;both name and type 

;name only 

fn-l)*16,@c ??to select the fcb 
;past fcb definition 
;space for drive/filename/type 
;;series of db's 

?past initialized fcb 

;use default drive if name is zero 

+1 ;;use specified drive 

?fill file name 

file type with padded blanks 

;and three character type 

$-12 ;;beginning of the fcb 

;extent field 00 for setfile 
byte field, and disk map 
;x,x,rc,dm0...dml5,cr fields 


if fid&typ<=2 ;;in/outfile 

;; generate constants for infile/outfile 

fillnxt ;;@nxtb=0 on first call 

if bs+0<@sect 

;; bs not supplied, or too small 

@bs set @sect ;;default to one sector 

else 

;; compute even buffer address 

@bs set (bs/@sect)*@sect 

endif 


;; now define buffer base address 

if nul ba 

;; use next address after @nxtb 

fid&buf set buffers+@nxtb 

;; count past this buffer 

@nxtb set @nxtb+@bs 

else 

fid&buf set ba 

endif 


Listing 9-28. (continued) 
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?? fid&buf is buffer address 

fid&adr: 

dw fid&buf 

7 7 

fid&siz 
fid&len: 

dw 

fid&ptr: 


equ @bs ;;literal size 

@bs ;;buffer size 



ds 

2 77 set in infile/outfile 

7 7 

set device number 

@&f id 

set 

@nxtd ;;next device 

@nxtd 

set 

@nxtd+l 


endif 

7 ?of fid&typ<=2 test 

pfcb: 

endm 


file 

macro 

md,fid,dn,fn,ft,bs,ba 

7 7 

create 

file using mode md: 

7 7 

7 7 

7 7 


infile = 1 input file 

outfile = 2 output file 

setfile = 3 setup fcb 

7 7 

(see fillfcb for remaining parameters) 


local 

psub,msg,pmsg 


local 

pnd,eod,eob,pnc 

7 7 

construct the file control block 

t / 

fid&typ 

equ md ?;set mode for later 


fillfcb 

fid,dn,fn,ft,bs,ba 


if 

exitm 

endif 

md=3 ;;setup fcb only, so exit 


file control block and related parameters 
are created inline, now create io function 


jmp 

if 

get&fid: 

else 

put&fid: 

push 
end if 
lhld 
xchg 
lhld 
mov 
sub 
mov 
sbb 
jc 


psub ;;past inline subroutine 

md=l ;;input file 


psw ;;save output character 

fid&len ;;load current buffer length 
;;de is length 

fid&ptr ?;load next to get/put to hi 
a,l ??compute cur-len 

e 

a,h 
d 

pnc 


;;carry if next<length 
?;carry if len gtr current 
end of buffer, fill/empty buffers 
lxi h,0 

shld fid&ptr ;?clear next to get/put 


Listing 9-28. (continued) 


All Information Presented Here is Proprietary to Digital Research 


173 







Programmer's Utilities Guide 


9.4 Operating System Interface 


pnd: 
7 7 


7 7 

eod: 
7 7 


emsg: 


process next disk sector: 

xchg ;;fid&ptr to de 

lhld fid&len ;;do not exceed length 


de is 

next to fill/empty, hi is max len 

mov 

a,e 

;;compute next-len 

sub 

1 

;;to get carry if more 

mov 

a, d 


sbb 

h 

;;to fill 

jnc 

eob 


carry 

gen'ed, hence more to fill/empty 

lhld 

fid&adr 

;;base of buffers 

dad 

xchg 

d 

;;hi is next buffer addr 

mvi 

c,@dma 

;;set dma address 

call 

@bdos 

;;dma address is set 

lxi 

d,fcb&fid ;;fcb address to de 

if 

md=l 

;;read buffer function 

mvi 

c,@frd 

;;file read function 

else 

mvi 

c,@fwr 

;;file write function 

end if 
call 

@bdos 

;;rd/wr to/from dma address 

ora 

a 

;;check return code 

jnz 

eod 

;;end of file/disk? 

not end of file/disk, increment length 

lxi 

d, @sect 

;;sector size 

lhld 

fid&ptr 

;;next to fill 

dad 

d 


shld 

fid&ptr 

;;back to memory 

jmp 

pnd 

;;process another sector 

end of file/disk encountered 

if 

md=l 

;;input file 

lhld 

fid&ptr 

;;length of buffer 

shld 

else 

fid&len 

;;reset length 

fatal 

error, end of disk 

local 

emsg 


mvi 

c,@msg 

;;write the error 

lxi 

d,emsg 


call 

@bdos 

;;error to console 

pop 

psw 

;;remove stacked character 

jmp 

filerr 

;;usually reboots 

db 

cr, If 


db 

•disk full: &FID' 

db 




end if 


Listing 9-28. (continued) 


All Information Presented Here is Proprietary to Digital Research 


174 





Programmer's Utilities Guide 


9.4 Operating System Interface 


7 7 

eob: 

7? end of buffer, reset dma and pointer 

lxi d,@tbuf 

mvi c,@dma 

call @bdos 

lxi h,0 

shld fid&ptr ;;next to get 


pnc: 


process the next character 

xch 9 ??index to get/put in de 


lhld 

fid&adr 

7 ?base of buffer 

dad 

d 

77 address of char in hi 

xchg 


?7 address of char in de 

if 

md=l 

7 ?input processing differ; 

lhld 

fid&len 

77 for eof check 

mov 

a,l 

770000 ? 

ora 

h 


mvi 

a,eof 

77 end of file? 

r z 


7 ?zero flag if so 

ldax 

d 

;?next char in accum 

else 



store 

next character from accumulator 

pop 

psw 

?7 recall saved char 

stax 

d 

7 ?character in buffer 

end if 



lhld 

fid&ptr 

77 index to get/put 

inx 

h 


shld 

fid&ptr 

77 pointer updated 

return 

with non 

zero flag if get 

ret 




psub: ;?past inline subroutine 

xr a a ;;zero to acc 

sta fcb&fid+12 ;;clear extent 

sta fcb&fid+32 ;;clear cur rec 

lxi h,fid&siz ;;buffer size 

shld fid&len ;;set buff len 

if md=l ; 7 input file 

shld fid&ptr ,* 7 cause immediate read 

mvi c,@opn 7 ?open file function 

else 7 7 output file 

lxi h,0 7?set next to fill 

shld fid&ptr 77 pointer initialized 

mvi c,@del 

lxi d,fcb&fid ; ?delete file 

call @bdos ??to clear existing file 

mvi c,@mak 7 ?create a new file 

end if 


Listing 9-28. (continued) 
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msg: 


pmsg: 

/ 

finis 


eob?: 


peof: 


now open 
lxi 
call 
inr 
jnz 
mvi 
lxi 
call 
jmp 
db 
if 
db 
else 
db 

end if 
db 

endm 


(if input), or make (if output) 
d,fcb&fid 

@bdos ;;open/make ok? 

;;255 becomes 00 


a 

pmsg 

c, @msg 

d, msg 
@bdos 
filerr 
cr, If 
md=l 


;;print message function 
;;error message 
;;printed at console 
;;to restart 

;;input message 


'no &FID file' 

'no dir space: &FID' 


macro fid 

close the file(s) given by fid 

irp ?f,<fid> 

skip all but output files 

if ?f&typ=2 

local eob?,peof,msg,pmsg 

write all partially filled buffers 

;;are we at the end of a buffer? 

lhld ?f&ptr ;;next to fill 

mov a,l ;;on buffer boundary? 

ani (@sect-l) and Offh 

jnz peof ;;put eof if not 00 

if @sect>255 

check high order byte also 

mov a,h 

ani (@sect-l) shr 8 

jnz peof ;;put eof if not 00 

endif 

arrive here if end of buffer, set length 
and write one more byte to clear buffs 


shld 

mvi 

push 

call 

pop 

jnz 


?f&len 
a,eof 
psw 

put&?f 
psw 
eob? 


;?set to shorter length 
;;write another eof 
;;save zero flag 


;;recall zero flag 
;;non zero if more 

buffers have been written, close file 
mvi c,@cls 

lxi d,fcb&?f 

call @bdos 

inr a ;;255 if err becomes 00 

jnz pmsg 

file cannot be closed 


;?ready for call 
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mvi 

c,@msg 


lxi 

d,msg 


call 

@bdos 


jmp 

pmsg ;;error message printed 

msg: 

db 

cr, If 


db 

'cannot close &?F' 

pmsg: 

db 

end if 



endm 

7 7 of the irp 


endm 

7 

erase 

macro 

fid 

7 7 

delete 

the file(s) given by fid 


irp 

?f,<fid> 


mvi 

c,@del 


lxi 

d,fcb&?f 


call 

@bdos 


endm 

;;of the irp 


endm 

7 

direct 

macro 

fid 

7 7 

perform directory search for file 

7 7 

sets zero flag if not present 


lxi 

d,fcb&fid 


mvi 

c,@dir 


call 

@bdos 


inr 

a ; 00 if not present 


endm 

7 

rename 

macro 

new,old 

7 7 

rename 

file given by "old" to "new" 


local 

psub,renO 

7 7 

include 

the rename subroutine once 


jmp 

psub 


@rens: ;?rename subroutine, hi is address of 
;;old fob, de is address of new fcb 


push 

h 

;;save for rename 

lxi 

b, 16 

7 7 b=00,c=16 

dad 

b 

7 7 hi = old fcb+16 

ldax 

d 

?;new fcb name 

mov 

m,a 

77 to old fcb+16 

inx 

d 

;?next new char 

inx 

h 

7 ?next fcb char 

dcr 

c 

??count down from 16 

jnz renO 

old name in first half, new in second half 

pop 

d 

7 ?recall base of old name 

mvi 

c, @ren 

77 rename function 


Listing 9-28. (continued) 
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call 

ret 

psub: 

rename macro 
lxi 
lxi 
call 
endm 
rename 
endm 


@bdos 

;;rename complete 

n,o 

predefine rename 

h,fcb&o 

;;old fcb address 

d,fcb&n 

;;new fcb address 

@rens 

;;rename subroutine 

new,old 



get macro dev 

;; read character from device 

if @&dev <= @lst 

;; simple input 

mvi c,@&dev 

call @bdos 

else 

call get&dev 

endm 


r 

put macro dev 

;; write character from accum to device 

if @&dev <= @lst 

;; simple output 

push psw ;;save character 

mvi c,@&dev ?;write char function 

mov e,a ;?ready for output 

call @bdos ;;write character 

pop psw ;;restore for testing 

else 

call put&dev 

endm 


Listing 9-28. (continued) 


The equates that follow define the usual BDOS entry points and 
functions along with the disk sector size (@SECT) and special 
nongraphic characters (EOF, CR, LF, and TAB). The equates for @KEY 
through @LST are used in the GET and PUT macros to determine the 
source or destination device. The INFILE, OUTFILE, and SETFILE 
equates are used in the FILE macro as mnemonics for the file mode 
attribute. 

FILLNAM is a utility macro used in the construction of a File 
Control Block. FILLNAM accepts a filename or filetype along with a 
field size and builds a sequence of DBs that fill the name or type 
field with padded blanks. 
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FILLDEF is a utility macro similar to FILLNAM, but FILLDEF 
fills the File Control Block name or type field from the default 
File Control Block at @TFCB or @TFCB+16. FILLDEF is invoked to 
extract either the default filename (first eight characters) or 
default filetype (following three-character field). 

The FILLDEF macro constructs an inline subroutine to perform 
the data move operation the first time it is invoked and calls the 
inline subroutine (@DEF) on subsequent invocations. 

FILNXT initializes two assembly time variables: @NXTB and 

@NXTD• @NXTB counts the accumulated size of buffers as they are 
automatically allocated in the FILE statement. @NXTD counts files 
in the FILE macro for later reference in GET and PUT statements. 
They are included within a macro, so that they are properly 
initialized in the two successive passes of the macro assembler. 
FILLNXT is invoked by the FILE macro where the expansion initializes 
@NXTB and @NXTD. FILLNXT then redefines itself as an empty macro, 
so that subsequent FILE invocations do not reset the two counters. 

The macro FILLFCB constructs a File Control Block in the CP/M 
standard format, where FID is the file identifier; DN is the disk 
name; FN is the filename; FT is the filetype; BS is the buffer size, 
and BA is the buffer address, as described in the FILE statement 
above. Recall that some of these parameters might be empty, causing 
default conditions to be selected. 

The FILLFCB macro begins by searching for a "1" or a "2" as the 
FN parameter, indicating that default name 1 or 2 is to be selected 
for the file. The IRPC loop involving ?C results in a value of 1 
for @C if either FN=1 or FN=2, and a value of 0 for @C if FN is not 
1 or 2. The FILLFCB macro then selects either the default name or 
the user-specified name along with the default or user-specified 
drive number. The equate for FCB&FID then produces the address of 
the File Control Block for the file identifier followed by DB 0 for 
the extent field and DS 20 for the remainder of the File Control 
Block. 

The remainder of the FILLFCB macro is devoted to storage 
allocation for buffer areas. The @BS variable is set to the buffer 
size after rounding and size checks. FID&BUF then becomes the 
address of the file buffer area, and FID&ADR labels a DW containing 
this literal value. FID&SIZ becomes the literal size of the buffer, 
and FID&LEN labels a DW containing the literal size. FID&PTR is 
also allocated as a double byte that subsequently holds the buffer 
index of the next character to get or put in the file. All of these 
values are used in the file operations that occur later. 

The principal file access macro, FILE, sets up the File Control 
Block, buffers, and access subroutines for a file. Similar to the 
FILLFCB macro, the parameters FID, DN, FN, FT, BS, and BA describe 
the particular characteristics of a file. The MD parameter, 
however, indicates the file mode and must have the value 1, 2, or 3. 
The FILE macro begins by assigning the mode value to FID&TYP, so 
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that subsequent macros can determine the type of access for this 
file. The FILLFCB. macro is then invoked to construct the File 
Control Block for this macro and sets generally useful parameters 
for the file, as discussed previously. The FILE macro then 
generates the label GET&FID for input files or PUT&FID for output 
files, followed by a subroutine that GETS a single character or PUTS 
a single character for this file. 

The GETZ&FID reads a single character from the input buffer 
and, when the input buffer is exhausted, fills the buffer area again 
in preparation for following GET operations. Upon detecting a real 
end-of-file, the EOF character is returned with the zero flag set. 
Similarly, the PUT&FID subroutine generated for output files stores 
the accumulator character into the output buffer at the next 
character position and, when the buffer is full, writes the sequence 
of sectors and returns to accept more output characters. In the 
case of an output error, the appropriate message is printed, and 
control transfers to FILERR, which usually remains at 0000H, causing 
a system reboot. 

The generated code that follows the label PSUB initializes the 
file pointers to the proper position for file access. The file 
extent and next record fields of the File Control Blocks are zeroed 
for both input and output files. In the case of an input file, the 
buffer index variable FID&PTR is set to the end of the buffer, 
causing an immediate read operation when the first character is 
read. In the case of an output file, the FID&PTR is set to zero, 
indicating that the next position to fill is the first character of 
the output buffer. If the file is an output file, any duplicate 
files are erased, and a new file is created. In both cases, the 
file is opened upon completion of the FILE operation, and the buffer 
pointers are set for the next GET or PUT invocation. Note that the 
FILE statement is executable; it must occur ahead of the GET or PUT 
statements for the file and performs its function each time control 
passes through the FILE machine code. 

The FINIS macro serves to empty the output buffers and close 
the file for output. Input files are skipped because no actions 
need take place to close an input file. The FINIS macro fills the 
remaining buffer segment (one size sector) with EOFs, then writes 
the partially filled buffers. 

The ERASE macro accepts a file identifier or list of file 
identifiers and successively calls the BDOS to erase each file, 
while the DIRECT macro searches for a single file given by the file 
identifier FID. In the case of the DIRECT macro, the zero flag is 
cleared if the file exists. No prechecks are made to see if the 
file exists before the ERASE operation takes place, although erasing 
a nonexistent file is of no consequence. The DIRECT macro can, of 
course, be used to check if a file exists before the ERASE is 
executed. 

The RENAME macro allows a file to be renamed by accepting two 
file identifiers, denoted by NEW and OLD. These file identifiers 
must correspond to the FCB names created by FILLFCB in an earlier 
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FILE invocation, and have the effect of renaming the OLD file to the 
NEW filename. This is accomplished within the RENAME macro through 
an inline subroutine, called @RENS, which is included the first time 
the RENAME macro is invoked. The inline subroutine moves the new 
File Control Block information (first sixteen bytes) into the second 
half of the old File Control Block in the form required for a rename 
operation under CP/M. (See the CP/M documentation.) The BDOS is 
then called to perform the rename function. There is no check to 
ensure the old file exists before the rename takes place. 

The GET and PUT macros are similar in structure: both accept a 
device or file identifier as the formal parameter DEV and perform 
the corresponding input or output function on that device. If the 
device is a simple peripheral, the BDOS is called directly to 
perform the input and output function. If, instead, the device name 
was created by a FILE macro, the corresponding GET&FID or PUT&FID 
subroutine is called to accomplish the input or output operation. 
Note that the accumulator is preserved (PUSH PSW) upon output to a 
simple peripheral within the PUT macro; the save/restore sequence is 
performed within the PUT&FID subroutine if the destination is a disk 
file. 


Listings 9-29 shows the full expansion of a segment of the case 
conversion program of Listing 9-27 (using the "+M" assembly 
parameter). It begins with the invocation of FILE, followed by 
FILLFCB, again followed by FILLDEF. The @DEF subroutine is included 
inline, and the FILLDEF macro is redefined to exclude the 
subroutine. Upon completion of the FCB construction, the file 
parameters are generated, as shown in Listing 9-29b, along with the 
beginning of the GETSOURCE subroutine. 

The conditional assembly ignores the portions of this FILE 
macro expansion that are related to output files but includes the 
machine code for the input SOURCE file. In each case, the &FID 
labels result in names with the prefix or suffix SOURCE, associating 
the generated labels with this internal name. The machine code that 
initializes the File Control Block fields and buffer pointer follows 
the label ??0001. Upon completion of the FILE macro, the SOURCE 
file is ready for access. Each call to GETSOURCE reads one more 
character into the accumulator. Due to the length of the expanded 
macro form, the remainder of the case translation program is not 
shown. 

To illustrate the facilities of the SEQIO macro library, two 
additional programs are given. The first, called PRINT, formats the 
output from the macro assembler for printing on the system line 
printer. The second, called MERGE, performs a simple merge 
operation on two disk files. 
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FILE 

INFILE,SOURCE,,1,,2000 

+ 


LOCAL 

PSUB,MSG,PMSG 

+ 


LOCAL 

PND,EOD,EOB,PNC 

0001+= 

SOURCETYP 

EQU INFILE 

+ 


FILLFCB 

SOURCE,,1,,2000, 

+ 


LOCAL 

PFCB 

0001+# 

@c 

SET 

1 

+ 


I RPC 

?C,1 

+ 


IF 

NOT ('&?C' = *1* OR '&?C' = '2') 

+ 

@c 

SET 

0 

+ 


ENDM 


+ 


IF 

NOT ('l' = *1* OR *1* = *2*) 

+ 

@c 

SET 

0 

+ 


ENDM 


+ 


IF 

@c 

+ 


IF 

NUL 

000C+# 

@c 

SET 

12 

+ 


ELSE 


+ 

@c 

SET 

9 

+ 


ENDIF 


+ 


FILLDEF 

FCBSOURCE,(1-1)*16,@C 

+ 


LOCAL 

PSUB 

0103+C30F01 


JMP 

??0009 

+ 

@DEF: 



0106+7E 


MOV 

A,M 

0107+12 


STAX 

D 

0108+23 


INX 

B 

0109+13 


INX 

D 

010A+0D 


DCR 

C 

010B+C20601 


JNZ 

@DEF 

010E+C9 


RET 


+ 

??0009 

; 


+ 

FILLDEF 

MACRO ?FCB,?F,?L 

+ 


LXI 

H,@TFCB+?F 

+ 


LX I 

D,?FCB 

+ 


MVI 

C,?L 

+ 


CALL 

@DEF 

+ 


ENDM 


+ 


FILLDEF 

FCBSOURCE,(1-1)*16,@C 

010F+215C00 


LXI 

H,@TFCB+(1-1) *16 

0112+111D01 


LXI 

D,FCBSOURCE 

0115+0E0C 


MVI 

c,@c 

0117+CD0601 


CALL 

@DEF 

+ 


ENDM 


+ 


ENDM 


011A+C34401 


JMP 

??0008 

011D+ 

l 


DS 

@c 

T 

0000+# 

@CNT 

SET 

12-@C 

+ 


I RPC 

?FC, 

+ 


IF 

@CNT=0 OR NUL ?FC 


Listing 9-29. Sample FILE Expansion Segment 
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+ 

EXITM 


+ 

ENDIF 


+ 

DB 

'&?FC' 

+ 

@CNT SET 

@CNT-1 

+ 

ENDM 


+ 

IF 

@CNT=0 OR NUL 

+ 

EXITM 


+ 

REPT 

@CNT 

+ 

DB 

t i 

+ 

ENDM 


+ 

ENDM 


+ 

ELSE 


+ 

JMP 

??0008 

+ 

IF 

NUL 

+ 

DB 

0 

+ 

ELSE 


+ 

DB 

" = ^'+1 

+ 

ENDIF 


+ 

FILLNAM 

1,8 

+ 

FILLNAM 

,3 

+ 

ENDIF 


01lD+= 

FCBSOURCE 

EQU $-12 

0129+00 

DB 

0 

012A+ 

DS 

20 

+ 

IF 

SOURCETYP<=2 

+ 

FILLNXT 


0000+# 

@NXTB SET 

0 

0006+# 

@NXTD SET 

0LST+1 

+ 

FILLNXT 

MACRO 

+ 

ENDM 


+ 

ENDM 


+ 

IF 

2000+0<@SECT 

+ 

@BS SET 

@SECT 

+ 

ELSE 


0780+# 

@BS SET 

(2000/@SECT)*@SECT 

+ 

ENDIF 


+ 

IF 

NUL 

0370+# 

SOURCEBUF 

SET BUFFERS+0NXTB 

0780+# 

@NXTB SET 

@NXTB+@BS 

+ 

ELSE 


+ 

SOURCEBUF 

SET 

+ 

ENDIF 


+ 

SOURCEADR: 


013E+7003 

DW 

SOURCEBUF 

0780+= 

SOURCESIZ 

EQU @BS 

+ 

SOURCELEN: 


0140+8007 

DW 

@BS 

+ 

SOURCEPTR: 


0142+ 

DS 

2 

0006+# 

@SOURCE 

SET @NXTD 

0007+# 

@NXTD SET 

0NXTD+1 

+ 

ENDIF 



Listing 9-29. (continued) 
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??0008 

. 

ENDM 

+ 


IF 

INFILE=3 

+ 


EXITM 


+ 


ENDIF 


0144+C3B401 


JMP 

??0001 

+ 


IF 

INFILE=1 

+ 

GETSOURCE: 


+ 


ELSE 


+ 

PUTSOURCE: 


+ 


PUSH 

PSW 

+ 


ENDIF 


0147+2A4001 


LHLD 

SOURCELEN 

014A+EB 


XCHG 


014B+2A4201 


LHLD 

SOURCEPTR 

014E+7D 


MOV 

A, L 

014F+93 


SUB 

E 

0150+7C 


MOV 

A, H 

0151+9A 


SBB 

D 

0152+DA9D01 


JC 

??0007 

0155+210000 


LXI 

H,0 

0158+224201 


SHLD 

SOURCEPTR 

+ 

??0004 

s 


015B+EB 


XCHG 


015C+2A4001 


LHLD 

SOURCELEN 

015F+7B 


MOV 

A, E 

0160+95 


SUB 

L 

0161+7A 


MOV 

A, D 

0162+9C 


SBB 

H 

0163+D28F01 


JNC 

??0006 

0166+2A3E01 


LHLD 

SOURCEADR 

0169+19 


DAD 

D 

016A+EB 


XCHG 


016B+0E1A 


MVI 

C,@DMA 

016D+CD0500 


CALL 

@BDOS 

0170+111D01 


LXI 

D,FCBSOURCE 

+ 


IF 

INFILE=1 

0173+0E14 


MVI 

C,@FRD 

+ 


ELSE 


+ 


MVI 

C,@FWR 

+ 


ENDIF 


0175+CD0500 


CALL 

@BDOS 

0178+B7 


ORA 

A 

0179+C28901 


JNZ 

??0005 

017C+118000 


LXI 

D,@SECT 

017F+2A4201 


LHLD 

SOURCEPTR 

0182+19 


DAD 

D 

0183+224201 


SHLD 

SOURCEPTR 

0186+C35B01 


JMP 

??0004 


Listing 9-29. (continued) 
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+ 

??0005: 

+ 

IF 

0189+2A4201 

LHLD 

018C+224001 

SHLD 

+ 

ELSE 

+ 

LOCAL 

+ 

MVI 

+ 

LXI 

+ 

CALL 

+ 

POP 

+ 

JMP 

+ 

EMSG: DB 

+ 

DB 

+ 

DB 

+ 

END IF 

+ 

??0006: 

018F+118000 

LXI 

0192+0E1A 

MVI 

0194+CD0500 

CALL 

0197+210000 

LXI 

019A+224201 

SHLD 

+ 

??0007: 

019D+EB 

XCHG 

019E+2A3E01 

LHLD 

01A1+19 

DAD 

01A2+EB 

XCHG 

+ 

IF 

01A3+2A4001 

LHLD 

01A6+7D 

MOV 

01A7+B4 

ORA 

01A8+3E1A 

MVI 

01AA+C8 

RZ 

01AB+1A 

LDAX 

+ 

ELSE 

+ 

POP 

+ 

STAX 

+ 

END IF 

01AC+2A4201 

LHLD 

01AF+23 

INX 

01B0+224201 

SHLD 

01B3+C9 

RET 

+ 

??0001: 

01B4+AF 

XRA 

01B5+322901 

STA 

01B8 323D01 

STA 

01BB+218007 

LXI 

01BE+224001 

SHLD 

+ 

IF 

01C1+224201 

SHLD 

01C4+0E0F 

MVI 


Listing 9- 
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INFILE=1 

SOURCEPTR 

SOURCELEN 

EMSG 

C , @MSG 

D, EMSG 
0BDOS 
PSW 

FILERR 
CR, LF 

1 disk full: SOURCE' 


D,@TBUF 
C,@DMA 
§BDOS 
H, 0 

SOURCEPTR 


SOURCEADR 

D 

INFILE=1 

SOURCELEN 

A,L 

H 

A, EOF 
D 

PSW 

D 

SOURCEPTR 

H 

SOURCEPTR 


A 

FCBSOURCE+12 
FCBSOURCE+ 3 2 

H, SOURCESIZ 
SOURCELEN 
INFILE=1 
SOURCEPTR 

C,@OPN 

I. (continued) 
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+ 

ELSE 

+ 

LXI 

+ 

SHLD 

+ 

MVI 

+ 

LXI 

+ 

CALL 

+ 

MVI 

+ 

END IF 

01C6+111D01 

LXI 

01C9+CD0500 

CALL 

01CC+3C 

INR 

01CD+C2EC01 

JNZ 

01D0+0E09 

MVI 

01D2+11DB01 

LXI 

01D5+CD0500 

CALL 

01D8+C30000 

JMP 

01DB+0D0A 

??0002: 

+ 

IF 

01DD+6E6F20534F 

DB 

+ 

ELSE 

+ 

DB 

+ 

END IF 

01EB+24 

DB 

+ 

??0003: 

+ 

ENDM 


9.4 Operating System Interface 


H,0 

SOURCEPTR 

C, @DEL 

D, FCBSOURCE 
@BDOS 

C, @MAK 

D, FCBSOURCE 
@BDOS 

A 

??0003 
C , @MSG 
D,??0002 
@BDOS 
FILERR 

DB CR, LF 

INFILE=1 

'no SOURCE file' 

'no dir space: SOURCE' 


Listing 9-29. (continued) 


The PRINT program, shown in Listing 9-30, executes under the 
Console Command Processor and takes the following form: 

PRINT filename 

where filename is the name of a previously assembled program. PRINT 
assumes that there is a PRN file on the disk and possibly a SYM file 
on the same disk drive. The PRN file is first printed, with a form¬ 
feed at the top of each 56-line page. If the SYM file exists, it is 
also printed using the same formatting. If the files are 
successfully printed, they are both erased from the disk. 

The PRINT program begins by saving the console processor stack, 
with the intention of returning directly to the CCP without a system 
reboot. The input printer file is then defined with a FILE 
statement that specifies the internal name PRINT and obtains the 
filename from the console command line. The filetype, however, is 
set to PRN in this case. After performing an initial page eject, 
the program loops between the PRCYC (print cycle) and ENDPR (end 
print) labels by successively reading characters from the PRINT 
source and writing to the printer through the LISTING subroutine. 
On detecting an end-of-file character, control transfers to the 
ENDPR label where the PRN file is erased from the disk. 
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The program then checks for the presence of the SYM file by 
invoking the FILE macro with a SETFILE mode. This creates the 
proper File Control Block for the input file with type SYM but does 
not create buffers or open the file for access. Following the FILE 
macro, the DIRECT statement performs a directory search and, if the 
file is not present, control transfers to the ENDLST (end listing) 
label where execution terminates. 

If the SYM file exists, the program performs another page eject 
and then opens the SYM file for access. Note that the third FILE 
macro accesses the SYM file using the internal name SYMBOL but 
shares the buffer areas of the PRINT file. The PRINT file has been 
erased at this point, so the buffers are available. 

If the SYM file is present, the program loops between the 
SYCYCLE (symbol cycle) and ENDSY (end symbol) labels where 
characters are read from the SYMBOL file and again sent to the 
printer through the LISTING subroutine. Upon detecting the end-of- 
file, control passes to the ENDSY label where the SYM file is erased 
from the disk. If no errors occur, control eventually reaches the 
ENDLST label where the printer page is ejected. The entry stack 
pointer is then retrieved from OLDSP, and control returns to the 
Console Command Processor, completing execution of the PRINT 
program. 
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0100 ORG 100H 

MACLIB SEQIO ;SEQUENTIAL I/O LIB 
; PRINT THE X.PRN AND X.SYM FILES ON THE 




9 

i 

LINE PRINTER WITH PAGE FORMATTING. 

oooc 

_ 

FF 

EQU 

OCH 

;FORM FEED 

0038 

= 

MAXLINE 

EQU 

56 ;MAX LINES PER PAGE 



/ 

7 

SAVE THE ENTRY STACK POINTER 

0100 

210000 


LXI 

H,0 


0103 

39 


DAD 

SP 

;ENTRY SP TO HL 

0104 

22CF03 


SHLD 

OLDSP 

;SAVE ENTRY SP 

0107 

31CF03 


LXI 

SP,STACK 

;SET TO LOCAL STACK 

010A 


7 

FILE 

INFILE,PRINT,,1,PRN,1000 



; 

READ THE PRINT FILE UNTIL END OF FILE 

01F2 

CD8A03 


CALL 

EJECT 

;TOP OF PAGE 

01F5 


PRCYC: 

GET 

PRINT 


01F8 

FE1A 


CPI 

EOF 


01FA 

CA0302 


JZ 

ENDPR 

;SKIP IF END FILE 

01FD 

CD5103 


CALL 

LISTING 

;WRITE TO LISTING DEV 

0200 

C3F501 


JMP 

PRCYC 




ENDPR: 

;END OF 

PRINT FILE, DELETE IT 

0203 



ERASE 

PRINT 




9 

9 

CHECK FOR THE OPTIONAL .SYM FILE 

020B 



FILE 

SETFILE, 

SYMCHK,,1,SYM 

023A 



DIRECT 

SYMCHK 

;IS IT THERE? 

0243 

CA3C03 


JZ 

ENDLST 

;SKIP SYMBOL IF SO 



9 

9 

SYMBOL ] 

FILE IS PRESENT, PAGE EJECT 

0246 

CD8A03 


CALL 

EJECT 

;TO TOP OF PAGE 

0249 



FILE 

INFILE,SYMBOL,,1,SYM,1000,PRINTBUF 



SYCYCLE: 



0326 



GET 

SYMBOL 


0329 

FE1A 


CPI 

EOF 


032B 

CA3403 


JZ 

ENDSY 

;SKIP TO END ON EOF 

032E 

CD5103 


CALL 

LISTING 

;SEND TO PRINTER 

0331 

C32603 


JMP 

SYCYCLE 

;FOR ANOTHER CHAR 

0334 


ENDSY: 

ERASE 

SYMBOL 

;ERASE .SYM FILE 



ENDLST 

. 

;END OF 

LISTING - EJECT AND RETURN 

0 33C 

CD8A03 


CALL 

EJECT 


033F 

2ACF03 


LHLD 

OLDSP 

;ENTRY STACK POINTER 

0342 

F9 


SPHL 


;RESTORE STACK POINTER 

0343 

C9 


RET 


;TO CCP 



7 

7 

UTILITY 

SUBROUTINES 


/ u 
LISTOUT: 


Listing 9-30. Program for Line Printer Page Formatting 
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;SEND A SINGLE 

CHARACTER TO THE PRINTER 

0344 


PUT 

LST 


034C 

21D203 

LX I 

H,CHARC 

;CHARACTER COUNTER 

034F 

34 

INR 

M 

;INCREMENT POSITION 

0350 

C9 

RET 





i 

LISTING: 





;WRITE 

CHARACTER FROM REG-A TO LIST DEVICE 

0351 

FE0C 

CPI 

FF 

;FORM FEED? 

0353 

C25F03 

JNZ 

LIST0 


0356 

AF 

XRA 

A 

;CLEAR LINE COUNT 

0357 

32D103 

STA 

LINEC 


035A 

32D203 

STA 

CHARC 

;CLEAR TAB POSITION 

035D 

3E0C 

MVI 

A, FF 

;RESTORE FORM FEED 

035F 

FE0A 

LIST0: CPI 

LF 

? END OF LINE? 

0361 

G27403 

JNZ 

LIST1 


0364 

AF 

XRA 

A 

;CLEAR TAB POSITION 

0365 

32D203 

STA 

CHARC 


0368 

21D103 

LXI 

H,LINEC 

;LINE COUNTER 

036B 

34 

INR 

M 

;INCREMENTED 

036C 

7E 

MOV 

A,M 

;CHECK FOR END OF PAGE 

036D 

FE38 

CPI 

MAXLINE 

;LINE OVERFLOW? 

036F 

D8 

RC 


;RETURN IF NOT 

0370 

3600 

MVI 

M, 0 

?CLEAR LINEC 

0372 

3E0C 

MVI 

A, FF 

;SEND PAGE EJECT 

0374 

FE09 

LIST1: CPI 

TAB 

;TAB CHARACTER? 

0376 

C28703 

JNZ 

LIST2 




; FEED BLANKS TO NEXT TAB POSITION 

0379 

3E20 

TABOUT: 

MVI 

A, ' ' 

037B 

CD4403 

CALL 

LISTOUT 


037E 

3AD203 

LDA 

CHARC 

;CHARACTER POSITION 

0381 

E607 

ANI 

7H 

; MOD 8 

0383 

C27903 

JNZ 

TABOUT 

;FOR ANOTHER BLANK 



; ON CHARACTER BOUNDARY 

0386 

C9 

RET 





LIST2: ;SIMPLE 

CHARACTER 

0387 

C34403 

JMP 

LISTOUT 

;PRINT AND RETURN 



f 

EJECT: ;PERFORM PAGE EJECT 

038A 

3E0C 

MVI 

A, FF 

;FORM FEED 

038C 

C34403 

JMP 

LISTOUT 




! 

? DATA AREAS 


038F 


DS 

64 

? 32 LEVEL STACK 



STACK: 



03CF 


OLDSP: DS 

2 

;ENTRY STACK POINTER 

03D1 


LINEC: DS 

1 

;LINE COUNTER 

03D2 


CHARC: DS 

1 

;CHARACTER COUNTER 



/ 

BUFFERS: 



03D3 


END 





Listing 9- 

-30. (continued) 
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The next program, MERGE, is more complicated. The MERGE 
program accepts two filenames as input, taking the general command 
form 


MERGE filename 

where filename is the name of a master file, with assumed filetype 
of MAS, as well as an update name with assumed filetype UPD. The 
files consist of varying length records, each of which starts with a 
six-character numeric sequence number followed by textual material 
and ends with a carriage return line-feed sequence. The lines of 
information in the master and update files are assumed to be in 
ascending numeric order according to their sequence numbers. The 
MERGE program reads these two files and merges the records together 
to form a new file consisting of numerically ascending, sequence- 
numbered lines. 

Upon completion of the merge operation, the newly merged file 
becomes the new master file. Update records are properly 
interspersed within the new master file according to the numeric 
order, and any update record that matches a master record results in 
replacement of the master record by the update record. Upon 
successful completion of the merge operation, the original master 
file is renamed to have the filetype MBK (master back-up), the 
original update file is renamed to the filetype UBK (update back¬ 
up) , and the newly created file becomes the new MAS file. In this 
way, the operator can return to the back-up files in case of error, 
so that the source data is not destroyed. 
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0100 


0000 = 

0006 = 

03E8 = 

03E8 = 

07D0 = 

0100 31EC05 
0103 C3C801 


0106 FE30 
0108 D8 
0109 FE3A 
010B 3F 
010C C9 


010D 7570646174 
011E 6D61737465 


All Information 


BOOT 
SEQSIZ 
USIZE 
MSI ZE 
NSIZE 


ORG 10 OH 

FILE MERGE PROGRAM 

MACLIB SEQIO ;SEQUENTIAL FILE I/O 


EQU 

EQU 

EQU 

EQU 

EQU 


000OH ;SYSTEM REBOOT 

6 SIZE OF THE SEQUENCE #'S 

1000 ;UPDATE BUFFER SIZE 

USIZE ;MASTER BUFFER SIZE 

USIZE+MSIZE ;NEW BUFF SIZE 


LXI SP,STACK 

JMP START ;TO PERFORM THE MERGE 


; UTILITY SUBROUTINES 

7 

DIGIT: ;TEST ACCUMULATOR FOR VALID DIGIT 
; RETURN WITH CARRY SET IF INVALID 



CPI 

'O' 



RC 


;CARRY IF BELOW 0 


CPI 

'9' +1 

?CARRY IF BELOW 10 


CMC 


7NO CARRY IF BELOW 10 


RET 



7 

7 

ERROR 

MESSAGES FOR READU AND READM 

SEQERRU: 




DB 

1 update 

seq error',0 

SEQERRM: 



DB 

'master 

seq error',0 

7 

7 

GENERATE READU AND READM SUBROUTINES 


I RPC 

?F,UM 


7 

INLINE 

SEQUENCE 

NUMBER BUFFER 

7F&SEQ 

: 

DB 

0 ;TO START PROCESSING 


DS 

SEQSIZ-1 

;REMAINING SPACE FOR SEQ# 

READ&7F: 




LXI 

H,?F&SEQ 

;SEQUENCE BUFFER 


MOV 

A,M 

7 IS IT FF (END FILE) 1 


INR 

A 

;FF BECOMES 00 


RZ 


;SKIP THE READ 

7 

7 

READ THE SEQUENCE NUMBER PORTION 


MVI 

C,SEQSIZ 

;SIZE OF SEQUENCE # 

RD&7F&0: 



PUSH 

H 

;SAVE NEXT TO FILL 


PUSH 

B 

;SAVE NUMBER COUNT 


GET 

7F&FILE 

? READ THE FILE 


POP 

B 

;RECALL COUNT 


POP 

H 

;RECALL NEXT FILL 


CPI 

EOF 

;END FILE? 


Listing 9-31. File Merge Program 
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JZ 

EOF&7F 



CALL 

DIGIT 

;ASCII DIGIT? 


LXI 

D,SEQERR&7F 

;ERROR MESSAGE 


JC 

SEQERR 

;SEQUENCE ERROR 


; NO SEQUENCE ERROR, FILL NEXT DIGIT POSITION 


MOV 

M, A 



INX 

H 

;NEXT TO FILL 


DCR 

C 

;COUNT=COUNT-l 


JNZ 

RD&PF&0 

;FOR ANOTHER DIGIT 


RET 


;END OF FILL 


EOF&7F: 

;END OF FILE 

, SET SEQ# TO 0FFH 


MV I 

A,0FFH 



STA 

7F&SEQ 

;SEQ# SET TO FF 


RET 




ENDM 




SEQERR: 




; WRITE ERROR MESSAGE 

FROM (DE) TIL 00 

018F 1A 

LDAX 

D 


0190 B7 

ORA 

A 


0191 CA0000 

JZ 

BOOT 



; OTHERWISE, MORE TO PRINT 

0194 D5 

PUSH 

D 


0195 

PUT 

CON ;WRITE TO CONSOLE 

019D Dl 

POP 

D 


019E 13 

INX 

D 


019F C38F01 

JMP 

SEQERR ;FOR MORE CHARS 


WRITESEQ: 




;WRITE 

THE SEQUENCE 

NUMBER GIVEN BY HL 


;TO THE 

NEW FILE 


01A2 0E06 

MVI 

C,SEQSIZ 

;SIZE OF SEQ# 

01A4 7E 

WRIT0: MOV 

A,M 


01A5 23 

INX 

H 

?NEXT TO GET 

01A6 E5 

PUSH 

H 

;SAVE NEXT ADDR 

01A7 C5 

PUSH 

B 

;SAVE COUNT 

01A8 

PUT 

NEW 

;WRITE TO NEW 

01AB Cl 

POP 

B 

;RECALL COUNT 

01AC El 

POP 

H 

;RECALL ADDRESS 

01AD 0D 

DCR 

C 

;COUNT=COUNT-1 

01AE C2A401 

JNZ 

WRIT0 

;FOR ANOTHER CHAR 

01B1 C9 

RET 




COMPARE THE UPDATE SEQUENCE NUMBER WITH 
THE MASTER SEQUENCE NUMBER, SET: 

CARRY IF UPDATE < MASTER 
ZERO IF UPDATE = MASTER 
-ZERO IF UPDATE > MASTER 

Listing 9-31. (continued) 
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01B2 112F01 
01B5 215F01 
01B8 0E06 
01BA 1A 
01BB BE 
01BC D8 
01BD CO 

01BE FEFF 
01C0 C8 
01C1 13 
01C2 23 
01C3 OD 
01C4 C2BA01 
01C7 C9 


01C8 


02B0 


038C 

047D CD3501 
0480 CD6501 

0483 CDB201 
0486 CAAD04 
0489 D2C804 


COMPARE: 

LXI 
LXI 
MV I 

CLOOP: LDAX 
CMP 
RC 
RNZ 

; ITEMS 

CPI 
RZ 
INX 
INX 
DCR 
JNZ 
RET 


D,USEQ ;UPDATE SEQ# 

H,MSEQ ;MASTER SEQ# 

C/SEQSIZ ?SEQUENCE SIZE 

D ;UPDATE DIGIT 

M ;UPDATE-MASTER 

;CARRY IF LESS 
;NZERO IF GTR 

ARE THE SAME, CHECK FOR 0FFH 
OFFH ;END OF FILE 

;BOTH ARE OFFH 

D ;NEXT UPDATE 

H ;NEXT MASTER 

C ?COUNT DOWN 

CLOOP ;FOR ANOTHER DIGIT 

;ZERO FLAG IF EQUAL 


START: 


MAIN PROGRAM STARTS HERE 

;UPDATE FILE, WITH ASSUMED .UPD TYPE 
FILE INFILE,UFILE,,1,UPD,USIZE 
7 

;MASTER FILE, WITH ASSUMED TYPE .MAX 
FILE INFILE,MFILE,,1,MAS,MSIZE 
7 

<NEW FILE, TEMP.$$$ (RENAMED UPON EOF'S) 
FILE OUTFILE,NEW,,TEMP,$$$,NSIZE 
7 

CALL READU 7 INITIALIZE UPDATE RECORD 

CALL READM ;INITIALIZE MASTER RECORD 

MERGE: ;MAIN MERGING LOOP 

CALL COMPARE ;CARRY SET IF UPDATE<MASTER 
JZ SAME ;ZERO IF IDENTICAL SEQ# 

JNC MASLOW ;MASTER LOW? 


048C 

212F01 

LXI 

H,USEQ 

;COPY SEQUENCE NUMBER 

048F 

CDA201 

CALL 

WRITESEQ;WRITE THE SEQUENCE # 


¥ 

ULOOP: ;UPDATE 

RECORD 

TO NEW FILE 

0492 


GET 

UFILE 

;CHARACTER TO A 

0495 

F5 

PUSH 

PSW 

;SAVE IT 

0496 


PUT 

NEW 

;OUTPUT TO NEW FILE 

0499 

FI 

POP 

PSW 

;RECALL CHARACTER 

049A 

FE0A 

CPI 

LF 

;LINE FEED? 

049C 

CAA704 

JZ 

ENDUP 


049F 

FE1A 

CPI 

EOF 


04A1 

CAA704 

JZ 

ENDUP 


04A4 

C39204 

7 

JMP 

ULOOP 

;CYCLE IF NOT END REC 



Listing 9- 

-31. (continued) 
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04A7 CD3501 

ENDUP: CALL 

READU ;READ ANOTHER SEQ# 

04AA C38304 

JMP 

i 

MERGE ;FOR ANOTHER RECORD 


SAME: ;SEQUENCE NUMBERS ARE IDENTICAL 

04AD 3A5F01 

LDA 

MSEQ ;CHECK FOR 0FFH 

04B0 FEFF 

CPI 

0FFH 

04B2 CAE904 

JZ 

ENDMERGE 


• NOT THE 

SAME, DELETE MASTER RECORD 

04B5 

DELMAS: 

GET MFILE 

04B8 FE1A 

CPI 

EOF ;END OF FILE? 

04BA CAC204 

JZ 

GETMAS ?GET SEQ# FF 

04BD FEOA 

CPI 

LF 

04BF C2B504 

JNZ 

DELMAS ;FOR ANOTHER CHAR 

04C2 CD6501 

GETMAS: 

CALL READM ;TO NEXT RECORD 

04C5 C38304 

JMP 

MERGE ;FOR ANOTHER 


MASLOW: 

;MASTER SEQUENCE NUMBER IS LOW 

04C8 215F01 

LXI 

H,MSEQ 

04CB CDA201 

CALL 

WRITESEQ;SEQUENCE NUMBER 

04CE 

MLOOP: GET 

MFILE 

04D1 F5 

PUSH 

PSW ;SAVE MASTER CHARACTER 

04D2 

PUT 

NEW 

04D5 FI 

POP 

PSW ;LF OR EOF? 

04D6 FEOA 

CPI 

LF 

04D8 CAE304 

JZ 

ENDMS 

04DB FE1A 

CPI 

EOF 

04DD CAE304 

JZ 

ENDMS 

04E0 C3CE04 

JMP 

MLOOP ;MORE TO COPY 

04E3 CD6501 

ENDMS: CALL 

READM ;READ NEW SEQ NUMBER 

04E6 C38304 

JMP 

MERGE ;TO MERGE ANOTHER 


ENDMERGE: 



;CLOSE 

ALL FILES FOR RENAMING 

04E9 

FINIS 

<UFILE,MFILE,NEW> 


;OLD MASTER FILE FOR ERASE/RENAME 

0529 

FILE 

SETFILE,OLDMAS,,1,MBK 

0558 

ERASE 

OLDMAS 


;RENAME 

MASTER TO .MBK 

0560 

RENAME 

OLDMAS,MFILE 


•OLD UPDATE FILE FOR ERASE/RENAME 

0580 

FILE 

SETFILE,OLDUPD,,1,UBK 

05AF 

ERASE 

OLDUPD 


;RENAME 

UPDATE TO .UBK 

05B7 

RENAME 

OLDUPD,UFILE 


;RENAME 

NEW TO MASTER FILE 

05C0 

RENAME 

MFILE,NEW 

05C9 C30000 

JMP 

BOOT 


Listing 9-31. (continued) 
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# 

05CC DS 32 ;16 LEVEL STACK 

STACK: 

; BUFFER AREA 

BUFFERS: 

146C = MEMSIZE EQU BUFFERS+NXTB ;END OF MEMORY 

05EC END 

Listing 9-31. (continued) 


The MERGE program, shown in Listing 9-31, begins with utility 
subroutines, including the DIGIT subroutine that tests for valid 
decimal digits in sequence numbers. The IRPC that follows the DIGIT 
subroutine generates two distinct subroutines, called READU and 
READM, for reading the update and master files, respectively. The 
generation of these two subroutines has been suppressed in the 
listing to keep the listing short. (See Section 10.) These two 
READ subroutines fill their respective sequence number buffers from 
the input source, so that the merge operation can take place based 
on the current sequence number values. Upon detecting an end-of- 
file, the sequence number is set to OFFH as a signal that the input 
source has been exhausted. 

The SEQERR subroutine reports an error condition when a 
nonnumeric character is detected in the sequence number field. 
Although the error reporting is spartan, sequence errors are easily 
found using the TYPE command on the master or update file. The 
WRITESEQ subroutine is called whenever the source for the next 
record has been determined. The COMPARE subroutine determines the 
next source record (master or update) by comparing the buffered 
sequence numbers from left to right while they are equal. If a 
mismatch occurs in the sequence number scan, COMPARE returns with 
the carry flag and zero flag set to indicate which file holds the 
next source record. 

Execution of the MERGE program begins following the START label 
where the update, master, and new files are defined. The UFILE and 
MFILE sources are defined with the same buffer sizes, as determined 
by the earlier USIZE and MSIZE equates. Both take their primary 
name from the default value specified at the CCP level by the 
operator. The new file is created as a temporary, with filename 
TEMP and filetype $$$, but is renamed upon completion of the program 
to become the master file. 

The merge operation proceeds in Listing 9-31b as follows. 
First the READU and READM subroutines are called to fill the 
sequence number buffers. The loop between MERGE and ENDMERGE is 
then repetitively executed until the merge is complete. On each 
iteration of this loop, the COMPARE subroutine is called to compare 
the buffered sequence numbers. If the update sequence number is 
smaller than the master sequence number, it is moved to the new 
file, and data is copied from the update file to the new file until 
the end of the current record is encountered. Upon completion of 
the copy operation, the READU subroutine is called again to refill 
the update sequence number buffer. 
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If the COMPARE, subroutine instead detects equal sequence 
numbers, control transfers to the SAME label, where the master 
record is deleted. Alternatively, the COMPARE subroutine causes 
control to transfer to the MASLOW label when the master sequence 
number is lower than the update sequence number. In this case, the 
master sequence number and data record are copied to the new file in 
exactly the same manner as an update record. 

Upon completion of the merge operation, indicated by an end-of- 
file in both the update and master files, control transfers to the 
ENDMERGE label where the files are closed and renamed. Following 
the FINIS statement, the previous MBK file (possibly from an earlier 
execution) is erased so that the current master (MAS) can be renamed 
to the master back-up (MBK). Similarly, any previous UBK file is 
erased, and the current update file is renamed to become the new UBK 
file. Finally, the new file (TEMP.$$$) is renamed to become the new 
master file (MAS) before execution stops. 

Listing 9-32 shows an example of the files involved in a 
typical merge operation. In this application, the sequence numbers 
control the ordering of a list of names that is updated 
periodically. The NAMES.MAS file, which is the original master, is 
updated by merging with the NAMES.UPD file, also shown in the 
listing. The merge operation is initiated by typing 

MERGE NAMES 

and, upon completion, produces the new NAMES.MAS shown in the 
righthand column of Listing 9-32. 

The SEQIO library is typical of the interface you can construct 
to provide a higher level interface between assembly language 
programs and their operating environment. Although the library 
shown here performs only simple sequential file input/output, you 
can construct more comprehensive libraries for random access based 
on this library. 
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NAMES.MAS 

000100 ABERCROMBIE, SIDNEY 
000200 CARLSBAD, YOLANDA 
000300 EGGBERT,EBENEZER 
000400 GRAVELPAUGH, HORTENSE 
000500 ISENEARS, IGNATZ 
000600 KRABNATZ, TILLY 
000700 MILLYWATZ, RICARDO 
000800 OPFATZ, ADOLPHO 
000900 QUAGMIRE, DONALD 
001000 TWITSWEET, LADNER 
001090 VERANDA, VERONICA 
001100 WILLOWANDER, PRATNEY 
001200 YUPPGANDER, MANNY 


NAMES.UPD 

000110 BERNSWEIGER, ALFRED 
000200 CRUENCE, CLARENCE 
000210 DENNINGSKI, HUBERT 
000330 FINKLESTEIN, FRANK 
000410 HILLSENFIELDS, RANDOLPH 
000540 JOLLYFELLOW, JUNE 
000620 LAMBAA, WILLY 
000710 NEEBEND, ASTRID 
000820 PRATTWITZ, HEADY 
000930 RUBBLEMEYER, RUNYON 
000960 SWIGSTITTS, ULYSSES 
001010 UMPLANDER, XAVIER 
001110 XYLOPH, ERHARDT 
001210 ZEPLIPPS, EGGERWORTZ 


9.4 Operating System Interface 


new NAMES.MAS 

000100 ABERCROMBIE, SIDNEY 
000110 BERNSWEIGER, ALFRED 
000200 CRUENCE, CLARENCE 
000210 DENNINGSKI, HUBERT 
000300 EGGBERT, EBENEZER 
000330 FINKLESTEIN, FRANK 
000400 GRAVELPAUGH, HORTENSE 
000410 HILLSENFIELDS, RANDOLPH 
000500 ISENEARS, IGNATZ 
000540 JOLLYFELLOW, JUNE 
000600 KRABNATZ, TILLY 
000620 LAMBAA, WILLY 
000700 MILLYWATZ, RICARDO 
000710 NEEBEND, ASTRID 
000800 OPFATZ, ADOLPHO 
000820 PRATTWITZ, HEADY 
000900 QUAGMIRE, DONALD 
000930 RUBBLEMEYER, RUNYON 
000960 SWIGSTITTS, ULYSSES 
001000 TWITSWEET, LADNER 
001010 UMPLANDER, XAVIER 
001090 VERANDA, VERONICA 
001100 WILLOWANDER, PRATNEY 
001110 XYLOPH, ERHARDT 
001200 YUPPGANDER, MANNY 
001210 ZEPLIPPS, EGGERWORTZ 


Listing 9-32. Sample MERGE Disk Files 


End of Section 9 
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Assembly Parameters 


You can include assembly parameters when you invoke the 
assembler that controls various assembler functions. The macro 
assembler is initiated with the name of the source file, followed by 
a dollar sign ($) and the assembly parameters. The parameters are 
indicated by single controls that denote particular functions. The 
character on the left below controls the function shown to the 


right. 

Table 10-1. Assembly Parameters 

Character 

Function 

A 

the source disk for the .ASM file 

H 

the destination of the .HEX machine code file 

L 

the source disk for the .LIB files (see MACLIB) 

M 

MACRO listings in the .PRN file 

P 

the destination of the .PRN file containing the 
listing 

Q 

the listing of LOCAL symbols 

s 

the generation and destination of the .SYM file 

1 

pass 1 listing 


Any or all of the above parameters can be included. The A, H, 
L, and S parameters are followed by the drive name to obtain or 
receive the data, where the drives are labeled A, B, . . ., Z. By 
convention, the X disk corresponds to the user's console; the P disk 
corresponds to the system line printer (logical list device), and 
the Z disk corresponds to a null file that is not recorded. The 
following is a valid assembly parameter list following the MAC 
command and source filename 

$PB AA HB SX 

that directs the .PRN file to disk B, reads the .ASM file from disk 
A, directs the .HEX file to the B disk, and sends the .SYM file to 
the user's console. Blanks are optional between parameter 
specifications. 
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The parameters L, S, M, Q, and 1 can be preceded by + or - 
symbols that enable or disable their functions. These functions 
are: 

+L lists input lines read from the macro library (see MACLIB). 
-L suppresses listing of the macro library (default value)• 

+S appends the .SYM to the end of the .PRN output. 

-S suppresses the generation of the sorted Symbol Table. 

+M lists all macro lines as they are processed during assembly. 
-M suppresses all macro lines as they are read during assembly. 
*M lists only hex generated by macro expansions. 

+Q lists all LOCAL symbols in the symbol list. 

-Q suppresses all LOCAL symbols in the symbol list. 

+1 produces a listing file on first pass (for macro debugging). 
-1 suppresses listing on pass 1 (default). 


The following is an example of a valid assembly parameter list 
that uses a number of the parameter specifications given above: 

$PB+S-M HB 

In this case, the .PRN file is sent to disk B with the symbol list 
appended (no .SYM file is created), all macro generations are 
suppressed, and the .HEX file is sent to disk B with the .PRN file. 

The M parameter can be preceded by an asterisk (*) , causing the 
assembler to list only macro generations that produce machine code. 
The asterisk suppresses the listing of the instructions that are 
produced; positions beyond the hex fields are not listed. Under 
normal operation, the macro assembler lists only generations that 
produce machine code, along with the generated line. 

Given that disk d is the currently logged drive, the macro 
assembler defaults these parameters as follows: the .ASM and .LIB 
files are assumed to originate on drive d; the .HEX, .PRN, and .SYM 
files are sent to drive d; a Symbol Table is generated with LOCAL 
symbols suppressed. This means symbols beginning with ?? are not 
listed, and macro lines that generate machine code are listed. 
Note, however, that the filename following the MAC command can be 
preceded by a drive name, in which case the P parameter overrides 
the drive name, if supplied. Whenever a parameter is repeated in 
the assembly parameter specification, the last value is assumed. 
Valid assembly statements are shown below, assuming the file to be 
assembled is called SAMPLE. 
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MAC SAMPLE $PX+S-M 

assembles the file SAMPLE.ASM with listing to the console, symbols 
at the console, and no listing of generated macros. 

MAC A:SAMPLE $+S -M+Q 

assembles sample.ASM from disk A, creating sample.PRN with appended 
symbols on the currently logged drive, suppressing generated macros, 
and listing symbols that begin with the characters ?? in addition to 
the usually listed symbols. 

MAC SAMPLE 

assembles SAMPLE.ASM from the currently logged drive, creating 
SAMPLE.PRN along with sample.SYM (containing the Symbol Table) and 
SAMPLE.HEX, which holds the Intel format hex file in the ASCII form. 

MAC SAMPLE $AB HA PB +Q +S +L *M 

assembles the SAMPLE.ASM file from drive B and produces the file 
SAMPLE.HEX on drive A, with the SAMPLE.PRN file on drive B. The 
Symbol Table includes ?? symbols. The Symbol Table is placed at the 
end of the .PRN file on drive B. The .LIB files are listed with the 
.PRN file as the .LIB files are read. The instructions that 
correspond to generated macro lines are not included, although 
generated machine code is listed. 

In addition to the parameters shown above, you can intersperse 
controls throughout the assembly language source or library files. 
Interspersed controls are denoted by a $ in the first column of the 
input line, where the form shown on the left below corresponds to 
the action described on the right. 


$-PRINT 
$+PRINT 
$-MACRO 
$+MACRO 
$*MACRO 


stops output listing by discarding formatted lines 
enables the output printing when previously disabled 
disables generated macro lines, as in -M above 
enables full macro trace, as in +M above 
enables partial macro trace, as in *M above 


Because MAC allows each line to be optionally prefixed by a line 
number, the $ control can be included directly following this line 
number. 


End of Section 10 
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Debugging Macros 


A number of common debugging practices can be used in 
developing macros and macro libraries. One technique, called 
iterative improvement, is often used in the design of programs and 
is most useful in building macros. The basic idea of iterative 
improvement is that a small portion of the overall macro set is 
first implemented and tested before continuing to more complicated 
macros. In this way, errors can be isolated at each step as the 
macro evolves. Further, if errors occur in the macro generations 
after a small portion of the macro set has been improved, it is most 
likely that the error is being caused by the macros that are 
changed. 

In the case of the Hornblower Highway System macro libraries, 
for example, iterative improvement was used to evolve the final 
macro library. Only the simplest macros were first implemented, 
including the SETLITE, TIMER, and RETRY macros. (See Section 9.) 
Debugging facilities were then added to these macros, so that the 
programs could be traced at the console. Upon successful testing of 
the basic macro facilities, the PUSH?, CLOCK?, and TREAD? macros 
were individually written and tested, resulting in the final macro 
library. 

At each step, you can use the various assembly parameters to 
control the debugging information. If the macro generations are not 
producing the proper machine code, it might be necessary to obtain a 
full trace, using the +M option when MAC is started. If the program 
produces too much output with the full trace enabled, you can use 
the $+MACRO and $-MACRO commands interspersed throughout the 
assembly language source program, resulting in full macro generation 
traces only in the regions selected for debugging consideration. 

If macro generation errors are caused by macro libraries, you 
can use the +L parameter when MAC starts to cause the libraries to 
be included in the listing as they are read. 

As a final consideration, it might be necessary to enable the 
first pass listing of the assembly language using the +1 parameter. 
In this case, MAC lists the program as it is being read on the first 
pass as well as the second pass. Note, however, that the listing 
contains spurious error messages on this pass that might disappear 
on the second pass. The first pass listing parameter allows you to 
view the macro generations on the two successive expansion passes to 
ensure that the assembler is processing the program in the same way 
in both cases. 

If a macro expands improperly, and the source of the error is 
not evident after examining various traces, it might be necessary to 
remove the offending macro from the program and create an isolated 
smaller test case where the error is reproduced. Full traces can 
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then be examined to determine the source of the error and, after 
fixing the macro, it can be replaced in the larger program and 
retested. 


End of Section 11 
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Symbol Storage Requirements 


The maximum program size that can be assembled by MAC is 
determined only by the Symbol Table storage requirements for the 
program. The Symbol Table itself occupies the region above the 
macro assembler in memory, up to the base of the CP/M operating 
system. Thus, the size of the Symbol Table depends on the size of 
the current MAC version—approximately 12K program and data, plus 
2.5K for I/O buffers—and the size of the user's CP/M configuration. 
The Symbol Table size is dynamically determined by MAC upon startup 
and fills as symbols are encountered. To provide some insight 
regarding storage requirements, the basic item size for identifiers 
and macros is given below. 

A name used as a program label, data label, or variable in a 
SET or EQUATE requires 

N = L + 5 

bytes, where L is the length of the identifier name. Thus, the 
statement 

PORTVAL EQU 37FH 

makes an entry into the Symbol Table that occupies 
N = 7 + 5 = 12 bytes 

of Symbol Table space. Recall that LOCAL symbols take the form 
??nnnn, which generates a name of length L = 6. 

Macro storage is more complicated to compute. The general form 
is 


M=L+7 + H + T 

where L is the macro name length; H is the parameter header storage 
requirement, and T is the macro text storage requirement, computed 
as 


H P i + P 2 + • • • + p n + n 

where P, is the length of the first parameter name. The text length 
T is the number of characters in the macro body, including tab and 
end-of-line characters. Reserved symbols, however, are reduced to a 
single byte from their multicharacter representations. The jump, 
call, and return on condition operators, however, require their full 
character representations. Comments starting with double semicolon 
are not included in the character count. The comment line is 
backscanned to remove preceding tab or blank characters in this 
case. For example, the macro 
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LOADR MACRO REG,ALPHA ;FILL REGISTER crlf 
MVI REG, 1 &ALPHA' ;;DATA crlf 

ENDM crlf 

contains a macro header, followed by two macro lines, where each 
line is written with tab characters (rather than spaces) and 
terminated by carriage return line-feeds (crlfs). 

In this case, the macro name length (LOADR) is five characters 
(L = 5), and the parameter name lengths are three characters (REG) 
and five characters (ALPHA), resulting in the following parameter 
header storage requirement: 


H=P 1 +P 2 +2=3+5+2=10 bytes 

The first macro line contains a leading tab (one byte), the MVI 
instruction (reduced to one byte), another tab character (one byte), 
the operands REG,'&ALPHA' (twelve characters), and the end of line 
(two characters), for a total of seventeen bytes. Note that the 
comment, with the preceding tab, is removed from the line. The 
second line contains a tab (one byte) , ENDM (one byte) , and end-of- 
line (two characters) for a total of four bytes. Summing the 
textual characters, the total is T = 21 bytes. As a result, the 
total macro storage for LOADP is 

M = L+ 7 + H + T= 5 + 7 + 10 + 21=43 bytes 

No permanent storage is required for REPTs, IRPCs, or IRPs, 
although temporary storage in the Symbol Table is used while the 
groups are actively iterating. The characters contained within the 
group bounds (from the header to the corresponding ENDM) are stored 
in the Symbol Table in their literal form, with no reduction of 
reserved symbols to single bytes. Upon completion of the iteration, 
the storage is returned for other purposes. Similarly, active 
parameters for macro expansions require temporary storage in the 
Symbol Table. Storage is returned upon completion of the macro 
expansion. 

In any case, a Symbol Table overflow message results if the 
total amount of free Symbol Table space is used up. As mentioned 
previously, the user can regenerate the CP/M system, up to the 
maximum memory space of the 8080 processor, to increase the symbol 
table area. The percentage of Symbol Table utilization is always 
printed at the console at the end of assembly. The printout takes 
the form: 

OhhH USE FACTOR 

where hh is a hexadecimal value in the range 00 to FF, where 00 
results from an almost empty table, and FF is produced from an 
almost full table. The value 080H, for example, is printed when the 
Symbol Table is half full. Keep note of the use factor as a program 
develops to gauge the relative amount of free space as the program 
is enhanced. 
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In many of the examples shown in this manual, macros include 
inline subroutines that are generated at the first invocation and 
called upon subsequent invocations. (See the TYPEOUT macro in 
Listing 6-11, for example.) These subroutines can be included in 
the mainline program to reduce Symbol Table storage requirements, if 
necessary. In this case, the subroutines are assumed to exist the 
first time the macro is invoked, and thus are not generated by the 
macro. 


End of Section 12 
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Section 13 

RMAC Relocating Macro Assembler 


RMAC, the CP/M Relocating Macro Assembler, is a modified 
version of the CP/M Macro Assembler (MAC). RMAC produces a 
relocatable object file (REL), rather than an absolute object file 
(HEX), that can be linked with other modules produced by RMAC, or by 
other language translators such as PL/I-80, to produce an absolute 
file ready for execution. The differences between RMAC and MAC are 
described in the following subsections. 


13.1 RMAC Operation 

RMAC takes the command form: 

RMAC filename.filetype 

followed by optional assembly parameters. If the filetype is not 
specified, ASM is assumed. RMAC produces three files: a list file 
(PRN), a symbol file (SYM), and a relocatable object file (REL). 
Characters entered in the source file in lower-case appear in lower¬ 
case in the list file, except for macro expansions. 

The assembly parameter H in MAC, used to control the 
destination of the HEX file, has been replaced by R, which controls 
the destination of the REL file. Directing the REL file to the 
console or printer (RX or RP) is not allowed, because the REL file 
does not contain ASCII characters. 

The following example directs RMAC to assemble the file 
TEST .ASM, send the PRN file to the console, and put the symbol file 
(SYM) and the relocatable object file (REL) on drive B. 

A>RMAC TEST $PX SB RB 


13.2 Expressions 

The operand field of a statement can consist of a complex 
arithmetic expression, as described in Section 3, with the following 
restrictions: 


• In the expression A+B, if A evaluates to a relocatable value or 
an external, then B must be a constant. 

• In the expression A-B, if A is an external, then B must be a 
constant. 
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• In the expression A-B, if A evaluates to a relocatable value, 
then B must be a constant, or B must be a relocatable value of 
the same relocation type as A. That is, both must appear in a 
CSEG or DSEG, or in the same COMMON block. 

• In all other arithmetic and logical operations, both operands 
must be absolute. 


An expression error ('E') is generated if an expression does 
not follow these restrictions. 


13.3 Assembler Directives 

The following assembler directives have been added to support 
relocation and linking of modules: 

ASEG use absolute location counter 

CSEG use code location counter 

DSEG use data location counter 

COMMON use common location counter 

PUBLIC symbol can be referenced in another module 

EXTRN symbol is defined in another module 

NAME name of module 


The directives ASEG, CSEG, DSEG, and COMMON allow program 
modules to be split into absolute, code, data, and common segments. 
These segments can be rearranged in memory as needed at link time. 
The PUBLIC and EXTRN directives provide for symbolic references 
between program modules. 

Note: symbol names can be up to 16 characters, but the first six 
characters of all symbols in PUBLIC, EXTRN, and COMMON statements 
must be unique, because symbols are truncated to six characters in 
the object module. 


13.3.1 The ASEG Directive 

The ASEG statement takes the form: 
label ASEG 

and instructs the assembler to use the absolute location counter 
until otherwise directed. The physical memory locations of 
statements following an ASEG are determined at assembly time by the 
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absolute location counter, which defaults to 0 and can be reset to 
another value by an ORG statement following the ASEG statement. 


13.3.2 The CSEG Directive 

The CSEG statement takes the form: 
label CSEG 

and instructs the assembler to use the code location counter until 
otherwise directed. This is the default condition when RMAC begins 
an assembly. The physical memory locations of statements following 
a CSEG statement are determined at link time. 


13.3.3 The DSEG Directive 

The DSEG statement takes the form: 
label DSEG 

and instructs the assembler to use the data location counter until 
otherwise directed. The physical memory locations of statements 
following a DSEG statement are determined at link time. 


13.3.4 The COMMON Directive 

The COMMON statement takes the form: 

COMMON /identifier/ 

and instructs the assembler to use the COMMON location counter until 
otherwise directed. The physical memory locations of statements 
following a COMMON statement are determined at link time. 


13.3.5 The PUBLIC Directive 

The PUBLIC statement takes the form: 

PUBLIC label{,label,...,label} 

where each label is defined in the program. Labels appearing in a 
PUBLIC statement can be referred to by other programs that are 
linked using LINK-80. 
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13.3.6 The EXTRN Directive 

The EXTRN statement takes the form: 

EXTRN label{,label,...,label} 

The labels appearing in an EXTRN statement can be referenced but 
must not be defined in the program being assembled. They refer to 
labels in other programs that have been declared PUBLIC. 


13.3.7 The NAME Directive 

The NAME statement takes the form: 

NAME 'text string' 

The NAME statement is optional. It is used to specify the name of 
the relocatable object module produced by RMAC. If no NAME 
statement appears, the filename of the source file is used as the 
name of the object module. Module names identify modules within a 
library when using the LIB-80 library manager. 


End of Section 13 
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XREF 


XREF is an assembly language cross-reference utility program 
used with the PRN and SYM files produced by MAC or RMAC to provide a 
summary of variable usage throughout the program. 

XREF takes the command form: 

XREF filename 

The filename refers to two input files that are created using MAC or 
RMAC with the assumed (and unspecified) filetypes of PRN and SYM, 
and one output file with an assumed (and unspecified) filetype of 
XRF. 


XREF reads the file filename.PRN line by line, attaches a 
line number prefix to each line, and writes each prefixed line to 
the file filename.XRF. During this process, XREF scans each line 
for any symbols that exist in the file filename.SYM. 

After completing this copy operation, XREF appends to the file 
filename.XRF a cross-reference report that lists all the line 
numbers where each symbol in filename.SYM appears. It also flags 
with a # character each line number where the referenced symbol is 
defined. 

XREF also reports the value of each symbol, as it appears in 
the file filename.SYM. 

As an option, the file specification can include a drive name 
in the standard CP/M format, d:. When the drive name is specified, 
XREF associates all the files described above with the specified 
drive. Otherwise, it associates the files with the default drive. 

XREF also allows you to direct the output file to the default 
list device instead of to the file filename .XRF. To use this 
option, add the string $p to the command line: 

XREF filename $P 

XREF allocates space for symbols and symbol references 
dynamically during execution. If no memory is available for an 
attempted symbol or symbol reference allocation, XREF issues an 
error message and terminates. 


End of Section 14 
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End of Section 14 
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Section 15 
LINK-80 


15.1 Introduction 

LINK-80 is a utility program you can use to combine relocatable 
object modules into an absolute file ready for execution under CP/M 
or MP/M II. 

There are two types of relocatable object modules. The first 
has a filetype of REL and is produced by PL/I-80, RMAC, or any other 
language translator that produces relocatable object modules in the 
Microsoft format. 

The second has a filetype of IRL and is generated by the CP/M 
library manager LIB-80. An IRL file contains the same information 
as a REL file but includes an index that enables faster searching of 
large libraries. 

Upon successful completion, LINK-80 lists the following items 
at the console: 

• the Symbol Table 

• any unresolved symbols 

• a Memory Map 

• the Use Factor 

The Memory Map shows the size and locations of the different 
segments. The Use Factor indicates the amount of available memory 
used by LINK-80 as a hexadecimal percentage. 

LINK-80 writes the Symbol Table to a SYM file suitable for use 
with the CP/M Symbolic Instruction Debugger (SID ) and creates a 
COM or PRL file for direct execution under CP/M or MP/M II. 


15.2 LINK-80 Operation 

LINK-80 takes the general command form: 

link filenamel{,filename2,...,filenameN} 

where f ilenamel,..., f ilenameN are the names of the object modules to 
be linked. If you do not specify a filetype, LINK-80 assumes 
filetype REL. 

LINK-80 produces two files: 

• filenamel.COM 

• filenamel.SYM 
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15.2 LINK-80 Operation 


You can specify a different name for the COM and SYM files with a 
command of the form: 

link newfilename=filenamel{,filename2,..., filenameN} 

LINK-80 supports a number of optional switches that control the 
link operation. These switches are described in the following 
section. 

During the link process, LINK-80 can create up to eight 
temporary files on the default disk. The files are named: 

XXABS•$$$ XXPROG.$$$ XXDATA.$$$ XXCOMM.$$$ 

YYABS.$$$ YYPROG.$ $ $ YYDATA.$ $ $ YYCOMM.$$$ 

LINK-80 deletes these files following termination. However, they 
can remain on the disk if LINK-80 halts due to an error condition 


15.3 Multiline Commands 

If a LINK-80 command does not fit on a single line (126 
characters), the command can be extended by terminating the command 
line with an ampersand character. The ampersand can appear after 
any character in the command and need not follow a filename. 

LINK-80 responds with an asterisk on the next line, at which 
point you can continue the command. LINK-80 allows any number of 
lines ending with the ampersand. The last line terminates with a 
carriage return, as in the following example. The Symbol Table and 
memory map would appear where vertical ellipses are shown. 

A>link main, iomodl, iomod2, iomod3, iomod4, iomod5, 6 
LINK 1.3 

*libl[s], lib2[s], lib3[s], lib4& 

Ms] , lastmod[p2000& 

*,d200] 


A> 

Mote: you can use XSUB to submit multiline commands to LINK-80. 


15.4 LINK-80 Switches 

LINK-80 supports optional run-time parameters called switches 
that control the link operation. All LINK-80 switches are enclosed 
in square brackets, separated by commas, and immediately follow one 
or more of the filenames in the command line. 
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All switches except the S switch can appear after any filename 
in the command line. The S switch must follow the filename to which 
it refers. For example, 

A>LINK TEST[L4000],IOMOD,TESTLIB[S,NL,GSTART] 


15.4.1 The Additional Memory (A) Switch 

The A switch provides additional space for Symbol Table storage 
by decreasing the size of LINK-80's internal buffers. Use this 
switch only when necessary, as indicated by a MEMORY OVERFLOW error. 
Using the A switch causes LINK-80 to store its internal buffers on 
the disk, slowing down the linking process considerably, while 
allowing linking of larger programs. 


15.4.2 The Data Origin (D) Switch 

The D switch specifies the origin of the data and common 
segments. If you do not use the D switch, LINK-80 places the data 
and common segments immediately after the program segment. 

The D switch takes the form: 

Dnnnn 

where nnnn is the data origin in hexadecimal. 


15.4.3 The Go (G) Switch 

The G switch specifies the label where program execution 
begins, if it does not begin with the first byte of the program 
segment. Using the G switch causes LINK-80 to put a jump to the 
label at the load address. 

The G switch takes the form: 

G<label> 


15.4.4 The Load Address (L) Switch 

The load address defines the base address of the COM file 
generated by LINK-80. The load address is usually 100H, which is 
the base of the Transient Program Area (TPA) in a standard CP/M 
system. The L switch also sets the program origin to nnnn, unless 
otherwise set by the P switch. 
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The L switch takes the forms 
Lnnnn 

where nnnn is the desired load address in hexadecimal. 

Note: COM files created with a load address other than 100H do not 
execute properly under a standard CP/M system. 


15.4.5 The Memory Size (M) Switch 

The M switch can be used when you are creating PRL files to 
indicate that the program requires additional data space for proper 
execution. 

The M switch takes the form: 

Mnnnn 

where nnnn is the amount of additional data space needed in 
hexadecimal. 


15.4.6 The No List (NL) Switch 

The NL switch suppresses the listing of the Symbol Table at the 
console. 


15.4.7 The No Recording of Symbols (NR) Switch 

The NR switch suppresses the recording of the Symbol Table file 
on the disk. 


15.4.8 The Output COM File (OC) Switch 

The OC switch directs LINK-80 to produce a COM file. This is 
the default condition for LINK-80. 


15.4.9 The Output PRL File (OP) Switch 

The OP switch directs LINK-80 to produce a page-relocatable PRL 
file rather than a COM file. See Section 7.1 of the MP/M II 
Operating System Programmer's Guide for more information on 
creating PRL fTTiFT .. 


9 
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15.4.10 The Program Origin (P) Switch 

The P switch specifies the origin of the program segment. If 
you do not use the P switch, LINK-80 puts the program segment at the 
load address, which is 100H unless otherwise specified by the L 
switch. 

The P switch takes the form: 

Pnnnn 

where nnnn is the program origin in hexadecimal. 


15.4.11 The ? Symbol (Q) Switch 

Symbols in many run-time subroutine libraries begin with a 
question mark to avoid conflict with user-defined symbols. LINK-80 
usually suppresses listing and recording of these symbols. 

The Q switch causes LINK-80 to include these symbols in the 
Symbol Table listed at the console and recorded on the disk. 


15.4.12 The Search (S) Switch 

The S switch indicates that the preceding file should be 
treated as a library. LINK-80 searches the file and includes only 
those modules containing symbols that are referenced but not defined 
in the modules already linked. 


15.5 The $ Switch 

The $ switch controls the source and destination devices. The 
$ switch takes the general form: 

$td 

where t is a type, and d is a drive specification. 

LINK-80 recognizes five types: 


• 

c - 

Console 

• 

I - 

Intermediate 

• 

L - 

Library 

• 

0 - 

Object 

• 

S - 

Symbol 


All Information Presented Here is Proprietary to Digital Research 

219 




Programmer's Utilities Guide 


15.5 The $ Switch 


The drive specification can be a letter in the range A through 
P corresponding to one of sixteen logical drives, or one of the 
following special characters: 


• X - Console 

• Y - Printer 

• Z - Byte bucket 


15.5.1 $Cd - Console 

LINK-80 usually sends messages to the console, but messages can 
be directed to the list device by using $CY, or they can be 
suppressed by using $CZ. Once $CY or $CZ has been specified, $CX 
can be used subsequently in the command line to redirect messages to 
the console device. 


15.5.2 $Id - Intermediate 

LINK-80 usually places the intermediate files it generates on 
the default drive. The $1 switch allows you to specify another 
drive for intermediate files. 


15.5.3 $Ld - Library 

LINK-80 usually searches on the default drive for library files 
that are automatically linked because of a request item in a REL 
file. The $L switch instructs LINK-80 to search the specified drive 
for these library files. 


15.5.4 $Od - Object 

LINK-80 usually generates an object file on the same drive as 
the first REL file in the command line, unless an output file with 
an explicit drive is included in the command. The $0 switch 
instructs LINK-80 to place the object file on the drive specified by 
the character following the $0, or to suppress the generation of an 
object file if the character following the $0 is a Z. 


15.5.5 $Sd - Symbol 

LINK-80 usually generates a symbol file on the same drive as 
the first REL file in the command line, unless an output file with 
an explicit drive is included in the command. The $S switch 
instructs LINK-80 to place the symbol file on the drive specified by 
the character following the $S, or to suppress the generation of a 
symbol file if the character following the $S is a Z. 
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15.5 The $ Switch 


15.5.6 Command Line Specification 

The td character pairs following a $ switch must not be 
separated by commas. The entire group of $ switches must be set off 
from any other switches by a comma. For example, the three command 
lines shown below are equivalent: 


A>link parti[$sz,$od,$lb,q],part2 
A>link parti[$szodlb,q],part2 
A>link parti[$sz od lb],part2[q] 


The $1 switch specifies the drive to be used for intermediate 
files during the entire link operation, but the other $ switches can 
be changed in the command line. The value of a $ switch remains in 
effect until it is changed as LINK-80 processes the command line 
from left to right. This is especially useful when linking 
overlays. (See Section 16.) For example, the command 

A>linx root (ovl[$szcz])(ov2)(ov3)(ov4[$sacx]) 

suppresses the SYM files and console output generated when 0V1, 0V2 
and 0V3 are linked. When 0V4 is linked, LINK-80 places the SYM file 
on drive A and sends any messages to the console device. 


15.6 Creating MP/M II PRL Files 

Assembly language programs often contain references to symbols 
in the Base Page such as BOOT, BDOS, DFCB, and DBUFF. To run 
properly under CP/M, or as a COM file under MP/M II, these symbols 
are simply defined in equates as follows: 


boot equ 
bdos equ 
dfcb equ 
dbuff equ 


0 

5 

5ch 

80h 


?jump to warm boot 
;jump to bdos entry point 
?default file control block 
ydefault i/o buffer 


With PRL files, however, the Base Page itself can be relocated 
at load time, so LINK-80 must know that these symbols, while at 
fixed locations within the Base Page, are relocatable. 

To do this, simply declare these symbols as externals in the 
modules in which they are referenced: 


extrn boot, bdos, dfcb, dbuff 
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and link in another module in which they are declared as publics and 
defined in equates: 



public 

boot. 

bdos, dcfb. 

dbuf f 

boot 

equ 

0 

;j ump to 

warm boot 

bdos 

equ 

5 

;jump to 

bdos entry point 

dfcb 

equ 

5ch 

;default 

file control block 

dbuf f 

equ 

end 

80h 

;default 

i/o buffer 


15.7 The Request Item 

Many language translators use the request item, a specific bit 
pattern in a REL file, to tell LINK-80 to search the appropriate 
run-time subroutine library file. When LINK-80 processes a library 
request, it first searches for an IRL file with the specified 
filename. If there is no IRL file, it searches for a REL file of 
that name. If both searches fail, then LINK-80 displays the 
following error message and halts. 

NO FILE: filename.REL 

Libraries requested in this manner appear in the Symbol Table listed 
at the console with a value of 'RQST'. 


15.8 REL File Format 

REL files contain information encoded in a bit stream, which 
LINK-80 interprets as follows: 


• If the first bit is a 0, then the next 8 bits are loaded 
according to the value of the location counter. 

• If the first bit is a 1, then the next 2 bits are interpreted 
as follows: 

00 - special link item, defined below. 

01 - program relative. The next 16 bits are loaded after 
being offset by the program segment origin. 

10 - data relative. The next 16 bits are loaded after 

being offset by the data segment origin. 

11 - common relative. The next 16 bits are loaded after 

being offset by the origin of the currently selected 
common block. 
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• A special item consists of: 

- A 4-bit control field that selects one of 16 special link 
items described below. 

- An optional value field that consists of a 2-bit address 
type field and a 16-bit address field. The address type 
field is interpreted as follows: 

00 - absolute 

01 - program relative 

10 - data relative 

11 - common relative 

- An optional name field that consists of a 3-bit name 
count followed by the name in 8-bit ASCII characters. 


The following special items are followed by a name field only. 

0000 - entry symbol. The symbol indicated in the name field 
is defined in this module, so the module should be 
linked if the current file is being searched, as 
indicated by the S switch. 

0001 - select common block. Instructs LINK-80 to use the 
location counter associated with the common block 
indicated in the name field for subsequent common 
relative items. 

0010 - program name. The name of the relocatable module. 

0011 - unused. 

0100 - unused. 


The following special items are followed by a value field and a name 


0101 - define common size. The value field determines the 
amount of memory reserved for the common block 
described in the name field. The first size allocated 
to a given block must be larger than or equal to any 
subsequent definitions for that block in other modules 
being linked. 

0110 - chain external. The value field contains the head of 
a chain that ends with an absolute 0. Each element of 
the chain is replaced with the value of the external 
symbol described in the name field. 

0111 - define entry point. The value of the symbol in the 
name field is defined by the value field. 

1000 - unused. 
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The following special items are followed by a value field only. 

1001 - external plus offset. The following two bytes in the 
current segment must be offset by the value of the 
value field after all chains have been processed. 

1010 - define data size. The value field contains number of 

bytes in the data segment of the current module. 

1011 - set location counter. Set the location counter to the 

value determined by the value field. 

1100 - chain address. The value field contains the head of a 

chain that ends with an absolute 0. Each element of 
the chain is replaced with the current value of the 
location counter. 

1101 - define program size. The value field contains the 

number of bytes in the program segment of the current 
module. 

1110 - end module. Defines the end of the current module. 

If the value field contains a value other than 
absolute 0, it is used as the start address for the 
program being linked. That is, the current module is 
the main module. The next item in the file starts at 
the next byte boundary. 


Item 1111, end file, has no value field or name field. This item 
follows the end module item of the last module in the file. 


15.9 IRL File Format 

An IRL file consists of three parts: a header, an index, and a 
REL section. 

The header contains 128 bytes, defined as follows: 

o byte 0 - extent number of first record of REL section 
o byte 1 - record number of first record of REL section 
o bytes 2-127 - currently unused 

The index consists of a number of entries corresponding to the entry 
symbol items in the REL section. The entries take the form: 


e 

r 

b 

cl 

c2 

. . 

cn 

d 










Figure 15—1. IRL File Index 
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15.9 IRL File Format 


where: 


e = extent offset from start of REL section to start of 
module. 

r = record offset from start of extent to start of module. 

b = byte offset from start of record to start of module. 

cl-cn = name of symbol. 

d = end of symbol delimiter (OFEH). 

The index terminates with an entry in which cl = OFFH. The 
remainder of the record containing the terminating entry is unused. 

The REL section contains the relocatable object code, as 
described in Section 15.8. 


End of Section 15 
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End of Section 15 
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Section 16 
Overlays 


16.1 Introduction 

You can use LINK-80 to produce a simple tree structure of 
overlays as shown in Figure 16-1. Currently, the Overlay Manager is 
part of the PL/I-80 run-time library. 


0V5 0V6 


0V1 0V2 0V3 0V4 


ROOT 


Figure 16-1. Tree-structured Overlay System 

In such a system, LINK-80 produces the ROOT.COM and ROOT.SYM 
files, as well as an OVL file and a SYM file for each overlay 
specified in the command line. 

The OVL file consists of a 256-byte header containing the load 
address and length of the overlay, followed by the absolute object 
code. The SYM file contains only those symbols that have not been 
declared in another module lower in the tree. 

The origin of an overlay is the highest address, rounded to the 
next 128-byte boundary, of the module below it on the tree. The 
stack and free space for the PL/I program are located at the top of 
the highest overlay which is, again, rounded to the next 128-byte 
boundary. LINK-80 displays this address at the console on 
completion of the entire link process and patches it into the root 
module in the location 1 7MEMRY 1 . 

The following restrictions must be observed when producing a 
system of overlays for a PL/I program using LINK-80: 

• Each overlay has only one entry point. The Overlay Manager in 
the PL/I Run-time system assumes that this entry point is at 
the base (load address) of the overlay. 

• No upward references are allowed from a module to an entry 
point in an overlay higher on the tree. The only exception is 
a reference to the main entry point of the overlay, as 
described above. Downward references to entry points in 
overlays lower on the tree or in the root module are allowed 
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• The overlays are not relocatable, so the root module must be a 
COM file. 

• Common blocks, EXTERNALS in PL/I, that are declared in one 
module cannot be initialized by a module higher in the tree. 
LINK-80 ignores any attempt to do so. 

• Overlays can be nested to 5 levels. 

• The Overlay Manager uses the default buffer located at 80H, so 
user programs should not depend on data stored in this buffer. 


16.2 Using Overlays in PL/I Programs 

There are two ways to use overlays in a PL/I program. The 
first method is straightforward and suffices for most applications. 
However, it has two restrictions. First, all overlays must be on 
the default drive, and second, the overlay names cannot be 
determined at run-time. 

The second method does not have these restrictions, but its 
calling sequence is slightly more complicated. 


16.2.1 Overlay Method 1 

To use the first method, simply declare an overlay as an entry 
constant in the module where it is referenced. As an entry 
constant, it can have parameters declared in a parameter list. The 
overlay itself is simply a PL/I procedure or group of procedures. 

For example, the following program is a root module having one 
overlay: 


root: procedure options (main); 

declare ovl entry (char (15)); 
put skip list ('root'); 
call ovl ('overlay 1'); 
end root; 

with the overlay 0V1.PLI defined as follows: 

ovl: procedure (c); 

declare c char (15); 
put skip list (c); 
end ovl; 

Note: when passing parameters to an overlay, you must ensure that 
the number and type of the parameters are the same in the calling 
program and the overlay itself. 
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To link these two programs into an overlay system, use the 
command: 


A>LINK ROOT (OV1) 

This causes LINK-80 to produce four files: 

ROOT.COM ROOT.SYM 0V1.0VL 0V1.SYM 

At execution time, ROOT.COM first displays the message 'root' 
at the console. The 'call ovl' statement then transfers control to 
the Overlay Manager. 

The Overlay Manager loads the file 0V1.0VL from the default 
drive at the proper location above ROOT.COM and transfers control to 
it, passing the CHARACTER(15) parameter in the usual manner. 

The overlay then executes, displaying the message 'overlay 1' 
at the console. It then returns directly to the statement following 
the 'call ovl' in ROOT.PLI, and execution continues from that point. 

If the Overlay Manager determines that the requested overlay is 
already in memory, then it does not reload the overlay before 
transferring control to it. 

There are several important points to keep in mind regarding 
overlay method 1: 

• The name associated with the overlay in the call and entry 
statements is the actual name of the OVL file loaded by the 
Overlay Manager, so the two names must agree. Because PL/I 
truncates symbol names to 6 characters in the REL file, the 
names of the OVL files must be limited to 6 characters. 

• The name of the entry point to an overlay (the name of the 
procedure) need not agree with the name used in the calling 
sequence. The same name should be used to avoid confusion. 

• The Overlay Manager loads overlays only from the drive that was 
the default drive when the root module began execution. The 
Overlay Manager disregards any changes in the default drive 
that occur after the root module begins execution. 

• The names of the overlays are fixed. This means the source 
program must be edited, recompiled, and relinked to change the 
names of the overlays. 

• No nonstandard PL/I statements are needed. Thus the program is 
transportable to other systems. 
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16.2.2 Overlay Method 2 

In some applications, it is useful to have greater flexibility 
with overlays, such as the ability to load overlays from different 
drives, or the ability to determine the name of an overlay at run¬ 
time, perhaps from the keyboard or from a disk file. 

To do this, a PL/I program must declare an explicit entry point 
into the Overlay Manager as follows: 

declare ?ovlay entry (char (10), fixed (1))? 

The first parameter is a character string specifying the name 
of the overlay to load and an optional drive name in the standard 
CP/M format, d:filename. 

The second parameter is the Load Flag. If the Load Flag is 1, 
the Overlay Manager loads the specified overlay whether or not it is 
already in memory. If the Load Flag is 0, then the Overlay Manager 
loads the overlay only if it is not already in memory. 

The 'call ?ovlay' statement signals the Overlay Manager to load 
the requested overlay, if needed. The Overlay Manager returns to 
the calling program, which must then perform a dummy call to execute 
the overlay just processed by the Overlay Manager. This allows a 
parameter list to be passed to the overlay. 

Using this method, the example shown in the first method above 
appears as follows: 

root: procedure options (main); 

declare ?ovlay entry (char (10), fixed (1)); 

declare dummy entry (char (15)); 

declare name char (10); 

put skip list ('root'); 

name = 'OV1*; 

call ?ovlay (name, 0); 

call dummy ('overlay 1'); 

end root; 

The file OV1.PLI is the same as before. 

At run-time, the Overlay Manager loads OVl.OVL from the default 
drive because that is the current value of the variable 'name', and 
then returns to the calling program, in this case, 'root.' 

At this point, the argument 'overlay 1' is set up according to 
the PL/1 parameter passing conventions. The 'call dummy' statement 
transfers control to the Overlay Manager, which in turn transfers 
control to the base address of the overlay the name of which it just 
processed. When OV1 finishes execution, it returns to the statement 
following the call dummy statement. 
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Note that in this example, name is set to '0V1' in an 
assignment statement. However, the overlay name can also be 
supplied as a character string from some other source, such as the 
console keyboard. 

Observe these important points when using overlay method 2: 

• A drive name can be specified, so the Overlay Manager can load 
overlays from drives other than the default drive. If no drive 
is specified, the Overlay Manager uses the default drive as 
described in Method 1. 

• The name of the overlay can be up to 8 characters in length 
because it is specified in the character string and not by the 
entry symbol. 

• If there are any parameters in the dummy call following the 
call ?ovlay, they must agree in number and type with the 
parameters in the procedure declaration in the overlay. 


16.3 Specifying Overlays in the Command Line 

The syntax for specifying overlays is similar to that for 
linking without overlays, except that each overlay specification is 
enclosed in parentheses. 

An overlay specification can take one of the following forms: 

A>LINK ROOT(0V1) 

A>LINK ROOT(OVl,PART2,PART3) 

A>LINK ROOT(OVl=PARTl,PART2,PART3) 

The first command produces the file 0V1.0VL from a file 
0V1.REL. The second command produces the file 0V1.0VL from 0V1.REL, 
PART2.REL, and PART3.REL. The third command produces the file 
0V1.0VL from PARTI.REL, PART2.REL, and PART3.REL. 

Note that a left parenthesis, indicating the start of a new 
overlay specification, also indicates the end of the group preceding 
it. Thus the following command line is invalid, and LINK-80 flags 
it as an error: 

A>LINK ROOT(OVl),MOREROOT 

All files to be included at any point on the tree must appear 
together, without any intervening overlay specifications. Thus the 
following command is valid: 

A>LINK ROOT,MOREROOT(OVl) 
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Any filename in the command line can be followed by a number of 
LINK-80 switches. The overlay specifications are not set off from 
the root module or from each other with commas. Spaces can be used 
to improve readability. 

To nest overlays, they must be specified in the command line 
with nested parentheses. For example, the following command line 
can link the overlay system shown in Figure 16-1: 

A>LINK ROOT (OV1) (OV2 (OV5) (OV6)) (OV3) (OV4) 


16.4 Sample LINK-80 Execution 

Listing 16-1 shows the console output from a LINK-80 operation. 
Note that 0V1 is flagged as an undefined symbol. LINK-80 indicates 
that 0V1 has not been defined in the current module and assumes it 
is either the name of an overlay or a dummy entry point to an 
overlay. 

When linking overlays, each entry variable that refers to an 
overlay, by actual name or a dummy entry, appears as an undefined 
symbol. No symbols other than these actual or dummy overlay entry 
points should be undefined. 

Listing 16-2 shows the console output when executing the 
resulting COM file. 
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A>link root(ovl) 

LINK 1.3 

PLILIB RQST ROOT 0100 /SYSIN/ 1A15 /SYSPRI/ 1A3A 

UNDEFINED SYMBOLS: 

OV1 


ABSOLUTE 
CODE SIZE 
DATA SIZE 
COMMON SIZE 
USE FACTOR 


0000 

18BC (0100-19BB) 
02A9 (1A90-1D38) 
00D4 (19BC-1A8F) 
4E 


LINKING OVl.OVL 


PLILIB RQST 


ABSOLUTE 
CODE SIZE 
DATA SIZE 
COMMON SIZE 
USE FACTOR 


0000 

0024 

0002 

0000 

09 


(1D80-1DA3) 

(1DA4-1DA5) 


MODULE TOP IE00 


Listing 16-1. LINK-80 Console Interaction 


A>root 

root 

overlay 1 

End of Execution 

A> 


Listing 16-2. Console Interaction with ROOT 
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16.5 Other Overlay Systems 

You can also use LINK-80 to produce a system of overlays that 
is not a tree structure, but contains instead a number of separate 
overlay areas, as shown in Figure 16-2. 



0V2A 


0V2B 

0V1A 

OVlB 


0V1C 

ROOT 


top of TPA 


— overlay area 2 


— overlay area 1 


100H 


Figure 16-2. Separate Overlay System 


In such a system, the root module can reference any of the 
overlays. An overlay can reference entry points in the root module 
or the main entry point of any overlay that is not in the same 
overlay area. 

Linking a system of overlays as shown above is done in a number 
of steps. One link operation must be performed for each overlay 
area because LINK-80 must be supplied the address of the top of the 
overlay area when linking the next higher overlay area. 

For example, from the command 

A>LINK ROOT (OV1A)(OVlB)(OV1C) 

LINK-80 generates the three overlays in overlay area 1 and indicates 
the top address of the module. This address is then supplied as the 
load address in the next commands 

A>LINK ROOT (OV2A[Lmod top]) (OV2B [Lmod top]) 
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This command creates the overlays for overlay area 2 at the 
appropriate address. Note that the overlay area that is the highest 
in memory should be linked last because LINK-80 always writes the 
module top address into the root module at the end of the link 
operation. 

At some point after the entire system has been linked, it is 
desirable to relink only one overlay, which might not be at the top 
overlay area. This can be done using the $0Z switch to prevent 
generation of a root module that would contain an erroneous 7MEMRY 
value. 

If only 0V1C is changed, the following command creates a new 
0V1C overlay without creating a new root module. The root module is 
included in the LINK command so that LINK-80 can resolve references 
to the root from 0V1C. 

For example, 

A>LINK ROOT [$0Z](OV1C[$OA]) 

Note: when using this type of overlay system, you must ensure that 
none of the overlays overlap and that no overlay attempts to 
reference another overlay in the same overlay area. 


End of Section 16 
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LIB-80 


17.1 Introduction 

LIB-80 is a utility program that creates libraries. Libraries 
are files consisting of any number of relocatable object modules. 
LIB-80 can perform the following functions: 

o concatenate a group of REL files into a library 
o create an indexed library (IRL) 

o select, delete, or replace modules from a library 
o print module names and PUBLICS from a library 


17.2 LIB-80 Operation 

LIB-80 takes the general command form: 

A>LIB filename=filenamel,...,filenameN 

This command creates a library called filename.REL from the files 
filenamel.REL,...,filenameN.REL. If you omit the filetypes, LIB-80 
assumes filetype REL. 

A filename can be followed by a group of module names enclosed 
in parentheses. Only the modules indicated are included in the LIB 
function being performed. If omitted, LIB-80 includes all the 
modules in the file. 

For example, the command 

A>LIB TEST=A(A1,A2),B,C(Cl—C4,C6) 

creates a file named TEST.REL consisting of the modules A1 and A2 
from A.REL, all the modules from B.REL, and the modules between Cl 
and C4, and C6 from C.REL. 

LIB-80 can delete or replace modules in a library with a single 
command. To do this, enter the names of the modules to be affected 
and enclose them in angle brackets immediately following the name of 
the source file that contains the modules. 

For example, the command 

A>LIB NEWLIB=OLDLIB<MODl> 

creates a new library named NEWLIB. REL that is the same as 
OLDLIB.REL except that the module MODI is replaced with the file 
MODI.REL. Use this form of the command if the name of the module 
being replaced is the same as the filename of the REL file replacing 
the module. 
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The command form: 

LIB NEWLIB=OLDLIB<MODl=FILEl> 

creates a new library with the module MODI replaced by the file 
FILEl.REL. Use this form of the command when the name of the module 
being replaced is not the same as the name of the file replacing it. 
This form of the command must be used if the filename within angle 
brackets has more than 6 characters because module names in the REL 
file are truncated to 6 characters. 

The command form 

LIB NEWLIB=OLDLIB<MOD1> 

creates a new library from OLDLIB.REL, deleting the module MODI. 
The command form 

LIB NEWLIB=OLDLIB<MODl,MOD2=FILE2,MOD3=> 

creates a new library from OLDLIB.REL with MODI.REL replacing the 
module MODI, FILE2.REL replacing M0D2, and deleting M0D3. This 
command demonstrates that a number of replace and/or delete 
instructions can be included within the angle brackets. 


17.3 LIB-80 Switches 

LIB-80 supports optional parameters in the command line that 
control its operation. These parameters are called switches. They 
are enclosed in square brackets and appear after the first filename 
in the LIB command. Table 17-1 shows the LIB-80 switches. 


Table 17-1. LIB-80 Switches 


Switch 

Function 

D 

displays contents of object modules in 


ASCII form. 

I 

creates an indexed library (IRL). 

M 

prints module names. 

P 

prints module names and PUBLICS. 


For example, the command 

A>LIB TEST=A,B,C 

creates a file TEST.REL consisting of A.REL, B.REL, and C.REL. 
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The command 

A>LIB TEST=TEST,D 

appends D.REL to the end of TEST.REL. 

The command 

A>LIB TEST[I] 

creates an indexed library TEST.IRL from TEST.REL. 

The command 

A>LIB TEST[I]=A,B,C,D 

performs the same function as the preceding examples, but LIB-80 
creates a file TEST.IRL without creating a file TEST.REL. 

The command 

A>LIB TEST [P] 

lists all the module names and PUBLICS in TEST.REL. 

End of Section 17 
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Appendix A 

MAC/RMAC Error Messages 


When errors occur within the assembly language program, they 
listed as single—character flags in the leftmost position of the 
source listing. The line in error is also echoed at the console so 
that the .PRN file need not be examined to determine if errors are 
present. The single-character error codes are listed in Table A-l. 


Table A-l. MAC/RMAC Error Messages 


Flag 

Meaning 

B 

Balance error: macro does not terminate properly, 
or conditional assembly operation is ill formed. 

C 

Comma error: expression was encountered but not 
delimited properly from the next item by a comma. 

D 

Data error: element in a data statement (DB or DW) 
cannot be placed in the specified data area. 

E 

Expression error: expression is ill formed and 

cannot be computed at assembly time. 

I 

Invalid character error: a nongraphic character has 
been found in the line other than a carriage return, 
line-feed, tab, or end-of-file? edit the file, 
delete the line with the I error, and retype the 
line. 

L 

Label error: label cannot appear in this context; 
it might be a duplicate label. 

M 

Macro overflow error: internal macro expansion 
table overflow; might be due to too many nested 
invocations or infinite recursion. 

N 

Not implemented error: features that appear in 

RMAC, such as relocation, are recognized, but 
flagged in MAC. 

0 

Overflow error: expression is too complicated 
(i.e., has too many pending operators), string is 
too long, or too many successive substitutions of a 
formal parameter by its actual value in a macro 
expansion. This error also occurs if the number of 
LOCAL labels exceeds 9999. 
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Table A—1# (continued) 


Flag 

Meaning 

P 

Phase error: label does not have the same value on 
the two passes through the program, or the order of 
macro definition differs between the two successive 
passes; might be due to MACLIB that follows a 
mainline macro; if so, move the MACLIB to the top of 
the program. 

R 

Register error: the value specified as a register 
is not compatible with the operation code. 

S 

Syntax error: the fields of this statement are ill 
formed and cannot be processed properly; might be 
due to invalid characters or delimiters that are out 
of place. 

U 

Undefined symbol: a label operand in this statement 
has not been defined elsewhere in the program. 

V 

Value error: operand encountered in an expression 
is improperly formed; might be due to delimiter out 
of place or nonnumeric operand. 


The error messages shown in Table A—2 indicate terminal error 
conditions that abort the MAC execution. Whenever possible, the 
disk drive name, followed by the relevant filename, is printed with 
the message. 


Table A-2. Terminal Error Conditions 


Message 


Meaning 


CANNOT CLOSE FILE: 

An output file cannot be closed. The disk 
might be write protected. 


INVALID PARAMETER: 

An invalid assembly parameter was found in the 
input line. The assembly parameters are 
printed at the console up to the point of the 
error. 
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Table A-2. (continued) 


Message 


Meaning 


NO DIRECTORY SPACE: 

The disk directory is full. Use the ERA 
command of the CCP to remove files you do not 
need. Often superfluous .HEX, .PRN, and .SYM 
files can be removed. 


NO SOURCE FILE PRESENT: 

The source program file (.ASM) following the 
MAC command cannot be found on the specified 
disk. Use the DIR command in the CCP to locate 
the source file. 


OUTPUT FILE READ ERROR: 

An output file cannot be written properly, 
probably due to a full disk. As in the NO 
DIRECTORY SPACE error above, use the CCP 
commands to erase unnecessary files from disk. 


SOURCE FILENAME ERROR: 

The form of the source filename is invalid or 
not specified. The command form must be 

MAC filename $assembly parameters 

where the filename is the primary name (up to 
eight characters) of the source file, with an 
assumed filetype of .ASM. Filetype is not 
specified. 


SOURCE FILE READ ERROR: 

The source file cannot be read properly by the 
macro assembler. Use the CCP TYPE command to 
display the file contents at the console. 
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Table A—2. (continued) 

Message 

Meaning 

UNBALANCED MACRO LIBRARY: 


A MACRO definition was started within a macro 
library, but the end of file was found in the 
library before the balancing ENDM was 
encountered. Examine the macro library using 
the TYPE command of the CCP f or use the +L 
assembly parameter to ensure that the library 
is properly balanced. 


End of Appendix A 
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XREF Error Messages 


During the course of operation, XREF might display error 
messages. These error messages and brief explanations of their 
causes are shown in Table B-l. 


Table B-l. XREF Error Messages 


Error 


Cause 


No SYM file 


The file filename.SYM is not present on 
the default or specified drive. 


No PRN file 

The file filename.PRN is not present on 
the default or specified drive. 


Symbol Table overflow 

No space is available for an attempted 
symbol allocation. 


Invalid SYM file format 

XREF issues this message when it reads an 
invalid filename.SYM file. Specifically, 
a line in the SYM file that does not 
terminate with a CRLF forces this error 
message. 


Symbol Table reference overflow 

No space is available for an attempted 
symbol reference allocation. 


filename.XRF make error 

XREF issues this message if the CP/M BDOS 
returns an error code after a make file 
request for the file filename.XRF. This 
error code usually indicates that no 
directory space exists on the default or 
specified drive. 
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Table 15-1. (continued) 


Error 

Cause 

filename.XRF close error 


XREF issues this message if the CP/M BDOS 
returns an error code after a close 
request for the file filename.XRF. 

filename.XRF write error 


XREF issues this message if the CP/M BDOS 
returns an error code after a write 
request for the file filename.XRF. This 
error code usually indicates that no 
unallocated data blocks are available, or 
no directory space exists on the default 
or specified drive. 


End of Appendix B 
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LINK-80 Error Messages 


When LINK-80 detects any kind of command line error, it echoes 
the command tail up to the point where the error occurs and follows 
it with a question mark. For example, 

A>link a, b, c; d 

A, B, C;? 

A>link longfilename 

LONGFILEN? 

During the course of operation, LINK-80 can display error 
messages. These error messages are described in Table C-l below. 


Table C-l. LINK-80 Error Messages 


Message 

Meaning 

CANNOT CLOSE: 

An output file cannot be closed. The disk 
might be write-protected. 

COMMON ERROR: 

An undefined common block has been 
selected. 

DIRECTORY FULL: 


There is no directory space for the output 
files or intermediate files. 

DISK READ ERROR: 


A file cannot be read properly. 

DISK WRITE ERROR: 


A file cannot be written properly, 
probably because the disk is full. 
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Table C-l. (continued) 


Message 

Meaning 

FIRST COMMON NOT LARGEST: 


A subsequent COMMON declaration is larger 
than the first COMMON declaration for the 
indicated block. Check that the files 
being linked are in the proper order, or 
that the modules in a library are in the 
proper order. 

INDEX ERROR: 

The index of an IRL file contains invalid 
information. 

INSUFFICIENT MEMORY: 


There is not enough memory for LINK-80 to 
allocate its buffers. Try using the A 
switch. 

INVALID REL FILE: 


The file indicated contains an invalid bit 
pattern. Make sure that a REL or IRL file 
has been specified. 

MAIN MODULE ERROR: 


A second main module was encountered. 

MEMORY OVERFLOW: 


There is not enough memory to complete the 
link operation. Try using the A switch. 

MULTIPLE DEFINITION: 


The specified symbol is defined in more 
than one of the modules being linked. 
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Table C-l. (continued) 


Message 

Meaning 

NO FILE: 

The indicated file cannot be found. 

OVERLAPPING SEGMENTS: 


LINK-80 attempted to write a segment into 
memory already used by another segment. 
Probably caused by incorrect use of P 
and/or D switches. 

UNDEFINED START SYMBOL: 


The symbol specified with the G switch is 
not defined in any of the modules being 
linked. 

UNDEFINED SYMBOLS: 


The symbols following this message are 
referenced but not defined in any of the 
modules being linked. 

UNRECOGNIZED ITEM: 


An unfamiliar bit pattern has been scanned 
and ignored by LINK-80. 


End of Appendix C 
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Appendix D 

Overlay Manager Run-time Error Messages 


At run-time, the Overlay Manager can display certain error 
messages. These messages and a brief explanation of their causes 
are shown in Table D-l. 


Table D-l. Run-time Error Messages 


Error 


Cause 


ERROR (8) OVERLAY, NO FILE d:filename.OVL 

The Overlay Manager cannot find the 
indicated file. 


ERROR (9) OVERLAY, DRIVE d:filename.OVL 

An invalid drive code was passed as a 
parameter to ?ovlay. 


ERROR (10) OVERLAY, SIZE d:filename.OVL 

The indicated overlay would overwrite the 
PL/I stack and/or free space if it were 
loaded. 


ERROR (11) OVERLAY, NESTING d:filename.OVL 

Loading the indicated overlay would exceed 
the maximum nesting depth. 


ERROR (12) OVERLAY, READ d:filename.OVL 

Disk read error during overlay load, 
probably caused by premature EOF. 


End of Appendix D 
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End of Appendix D 
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Appendix E 
LIB-80 Error Messages 


During the course of operation, LIB-80 can display error 
messages. These error messages and a brief explanation of their 
causes are given in Table E-l. 


Table E-l. LIB-80 Error Messages 


Error 

Cause 

CANNOT CLOSE: 

LIB-80 cannot close the output file. 
The disk might be write-protected. 

DIRECTORY FULL: 

There is no directory space for the 
output file. 

DISK READ ERROR: 

LIB-80 cannot read the file properly. 

DISK WRITE ERROR: 

LIB-80 cannot write to the file 
properly, probably due to a full 
disk. 

FILE NAME ERROR: 

The form of a source filename is 
invalid. 

NO FILE: 

LIB-80 cannot find the indicated 
file. 

NO MODULE: 

LIB-80 cannot find the indicated 
module. 

SYNTAX ERROR: 

The LIB-80 command line is not 
properly formed. 
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Appendix F 


8080 CPU 


OP 

CODE 

MNEMONIC 

OP 

CODE 

00 

NOP 


2B 

01 

LXI 

B, D16 

2C 

02 

STAX 

B 

2D 

03 

INX 

B 

2E 

04 

INR 

B 

2F 

05 

DCR 

B 

30 

06 

MVI 

B ,D8 

31 

07 

RLC 


32 

08 

— 


33 

09 

DAD 

B 

34 

0A 

LDAX 

B 

35 

0B 

DCX 

B 

36 

OC 

INR 

C 

37 

0D 

DCR 

C 

38 

0E 

MVI 

C ,D8 

39 

OF 

RRC 


3A 

10 

— 


3B 

11 

LXI 

D,D16 

3C 

12 

STAX 

D 

3D 

13 

INX 

D 

3E 

14 

INR 

D 

3F 

15 

DCR 

D 

40 

16 

MVI 

D ,D8 

41 

17 

RAL 


42 

18 

— 


43 

19 

DAD 

D 

44 

1A 

LDAX 

D 

45 

IB 

DCX 

D 

46 

1C 

INR 

E 

47 

ID 

DCR 

E 

48 

IE 

MVI 

E,D8 

49 

IF 

RAR 


4A 

20 

— 


4B 

21 

LXI 

H,D16 

4C 

22 

SHLD 

Adr 

4D 

23 

INX 

H 

4E 

24 

INR 

H 

4F 

25 

DCR 

H 

50 

26 

MVI 

H ,D8 

51 

27 

DAA 


52 

28 

— 


53 

29 

DAD 

H 

54 

2A 

LHLD 

Adr 

55 

81 

ADD 

C 

AC 

82 

ADD 

D 

AD 

83 

ADD 

E 

AE 

84 

ADD 

H 

AF 

85 

ADD 

L 

B0 
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Instructions 


MNEMONIC 

OP 

CODE 

MNEMONIC 

DCX 

H 

56 

MOV 

D ,M 

INR 

L 

57 

MOV 

D,A 

DCR 

L 

58 

MOV 

E ,B 

MVI 

L ,D8 

59 

MOV 

E ,C 

CMA 


5A 

MOV 

E ,D 

— 


5B 

MOV 

E,E 

LXI 

SP,D16 

5C 

MOV 

E,H 

STA 

Adr 

5D 

MOV 

E,L 

INX 

SP 

5E 

MOV 

E ,M 

INR 

M 

5F 

MOV 

E ,A 

DCR 

M 

60 

MOV 

H,B 

MVI 

M ,D8 

61 

MOV 

H ,C 

STC 


62 

MOV 

H,D 

— 


63 

MOV 

H ,E 

DAD 

SP 

64 

MOV 

H ,H 

LDA 

Adr 

65 

MOV 

H,L 

DCX 

SP 

66 

MOV 

H ,M 

INR 

A 

67 

MOV 

H ,A 

DCR 

A 

68 

MOV 

L ,B 

MVI 

A ,D8 

69 

MOV 

L ,C 

CMC 


6A 

MOV 

L,D 

MOV 

B,B 

6B 

MOV 

L ,E 

MOV 

B,C 

6C 

MOV 

L ,H 

MOV 

B ,D 

6D 

MOV 

L ,L 

MOV 

B f E 

6E 

MOV 

L ,M 

MOV 

B ,H 

6F 

MOV 

L,A 

MOV 

B,L 

70 

MOV 

M,B 

MOV 

B ,M 

71 

MOV 

M,C 

MOV 

B ,A 

72 

MOV 

M f D 

MOV 

C,B 

73 

MOV 

M r E 

MOV 

C,C 

74 

MOV 

M,H 

MOV 

C,D 

75 

MOV 

M f L 

MOV 

C ,E 

76 

HLT 


MOV 

C,H 

77 

MOV 

M ,A 

MOV 

C ,L 

78 

MOV 

A ,B 

MOV 

C ,M 

79 

MOV 

A ,C 

MOV 

C,A 

7A 

MOV 

A ,D 

MOV 

D, B 

7B 

MOV 

A,E 

MOV 

D,C 

7C 

MOV 

A ,H 

MOV 

D ,D 

7D 

MOV 

A, L 

MOV 

D,E 

7E 

MOV 

A ,M 

MOV 

D ,H 

IF 

MOV 

A, A 

MOV 

D ,L 

80 

ADD 

B 

XRA 

H 

D7 

RST 

2 

XRA 

L 

D8 

RC 


XRA 

M 

D9 

— 


XRA 

A 

DA 

JC 

Ad 

ORA 

B 

DB 

IN 

D8 
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8080 CPU Instructions in Operation Code Sequence (continued) 


OP 



OP 



OP 



CODE 

MNEMONIC 

CODE 

MNEMONIC 

CODE 

MNEMONIC 

86 

ADD 

M 

Bl 

ORA 

C 

DC 

CC 

Adr 

87 

ADD 

A 

B2 

ORA 

D 

DD 

— 


88 

ADC 

B 

B3 

ORA 

E 

DE 

SB I 

D8 

89 

ADC 

C 

B4 

ORA 

H 

DF 

RST 

3 

8A 

ADC 

D 

B5 

ORA 

L 

E0 

RPO 


8B 

ADC 

E 

B6 

ORA 

M 

El 

POP 

H 

8C 

ADC 

H 

B7 

ORA 

A 

E2 

JPO 

Adr 

8D 

ADC 

L 

B8 

CMP 

B 

E3 

XTHL 


8E 

ADC 

M 

B9 

CMP 

C 

E4 

CPO 

Adr 

8F 

ADC 

A 

BA 

CMP 

D 

E5 

PUSH 

H 

90 

SUB 

B 

BB 

CMP 

E 

E6 

AN I 

D8 

91 

SUB 

C 

BC 

CMP 

H 

E7 

RST 

4 

92 

SUB 

D 

BD 

CMP 

L 

E8 

RPE 


93 

SUB 

E 

BE 

CMP 

M 

E9 

PCHL 


94 

SUB 

H 

BF 

CMP 

A 

EA 

JPE 

Adr 

95 

SUB 

L 

CO 

RNZ 


EB 

XCHG 


96 

SUB 

M 

Cl 

POP 

B 

EC 

CPE 

Adr 

97 

SUB 

A 

C2 

JNZ 

Adr 

ED 

— 


98 

SBB 

B 

C3 

JMP 

Adr 

EE 

XRI 

D8 

99 

SBB 

C 

C4 

CNZ 

Adr 

EF 

RST 

5 

9A 

SBB 

D 

C5 

PUSH 

B 

F0 

RP 


9B 

SBB 

E 

C6 

ADI 

D8 

FI 

POP 

PSW 

9C 

SBB 

H 

C7 

RST 

0 

F2 

JP 

Adr 

9D 

SBB 

L 

C8 

RZ 


F3 

DI 


9E 

SBB 

M 

C9 

RET 

Adr 

F4 

CP 

Adr 

9F 

SBB 

A 

CA 

JZ 


F5 

PUSH 

PSW 

A0 

ANA 

B 

CB 

— 


F6 

ORI 

D8 

A1 

ANA 

C 

CC 

cz 

Adr 

F7 

RST 

6 

A2 

ANA 

D 

CD 

CALL 

Adr 

F8 

RM 


A3 

ANA 

E 

CE 

AC I 

D8 

F9 

SPHL 


A4 

ANA 

H 

CF 

RST 

1 

FA 

JM 

Adr 

A5 

ANA 

L 

DO 

RNC 


FB 

El 


A6 

ANA 

M 

Dl 

POP 

D 

FC 

CM 

Adr 

A7 

ANA 

A 

D2 

JNC 

Adr 

FD 

— 


A8 

XRA 

B 

D3 

OUT 

D8 

FE 

CPI 

D8 

A9 

XRA 

C 

D4 

CNC 

Adr 

FF 

RST 

7 

AA 

XRA 

D 

D5 

PUSH 

D 




AB 

XRA 

E 

D6 

SUI 

D8 





D8 = constant or logical/arithmetic expression that evaluates to an 
8 bit quantity. 

Adr = 16-bit address. 

Dl6 = constant or logical/arithmetic expression that evaluates to a 
16 bit data quantity. 

Reproduced with permission from Intel Corporation, Santa Clara, CA. 
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Index 


$ switches, 219, 220 
$Cd, 220 
$Id, 220 
$Ld, 220 
$Od, 220 
$Sd, 220 

8080 registers, 6 
?TR macro, 119 
??, 54 

A 

absolute file, 215 
absolute location counter, 210 
absolute object file, 209 
accumulator character, 165 
accumulator immediate 
instruction , 28 
accumulator/carry 
instructions, 32 
accumulator/register 
instructions, 32 
Actual parameters 5, 58, 130 
bracketed, 78 
options, 74 

additional memory switch, 217 
ADR macro, 118, 119 
alphabetic translation, 138, 167 
ampersand, 216 

concatenation operator, 75 
operator, 48 
string quotes, 7 
angle brackets 
leading, 74 
apostrophe 
double, 7, 65 
quoted string, 65 
leading, 74 
arithmetic logic unit 
operations, 32 
arithmetic operators, 8 
ASCII strings, 20, 21 
Assembler directives; also see 
Statements 
ASEG, 210 
COMMON, 210 
CSEG, 210 
DSEG, 210 
EXTRN, 210 
NAME, 210 
PUBLIC, 210 


Assembly parameters 
1, 199 
?? in, 200 
A, 199 

asterisk in, 200 
controls, 201 
debugging, 203 
default, 200 
disabled, 200 
enabled, 200 
H, 199 

L, 199 

M, 199 

P, 199 

Q, 199 
S, 199 

assembly process 
computations, 9 
restart, 120 
Asterisk 

in assembly parameters, 200 
in LINK-80, 216 
leading, 4 

B 

back-up files, 191 
base address, 22 
base page symbols, 221 
binary constant, 6 
blanks 

leading, 75 

boolean tests, 129, 130, 134 
bracket nesting, 50, 75 
bracketed expressions, 78 
bracketed notation, 79 
BRN macro, 120 
BUFFERS label, 170 

C 

call instruction, 25 
CASE program, 170 
CASE@m, 152 
character list, 49 
character strings, 7 
CLEAR macro, 118 
code location counter, 211 
comment field, 4 
COMPARE, 196 
COMPARE library, 134 
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concatenation operators, 45 
ampersand, 75 
condition flags, 25 
Conditional assembly 
and recursive, 71 
nested, 44 
with EXITM, 52 
with IF, ELSE, 

ENDIF, 15 to 18 
with NUL operator, 40 
conditional assembly groups, 17 
conditional branching, 119 
conditional tests, 120 
constant, 6 
constant labels, 44 
control instructions, 34 
Controlling identifiers, 45 
to 50 

translated to upper-case, 48 
controlling variable, 48 
conversion 

lower to upper-case, 169 
CPI instruction, 7 
cross-reference utility, 213 

D 

data location counter, 211 

data movement instructions, 29 

data origin switch, 217 

DB instruction, 7 

DB statement, 22 

DCL macro, 118 

DDT, 103, 104, 126 

debug flags, 89 

Debugging 

assembly parameters, 203 
codes, 89 
full trace, 203 
iterative improvement, 203 
macro, 119 

trace code generation, 125 
traces, 89, 103, 119, 125 
Debugging opcodes 
DMP, 103 
PRN msg, 103 
TRF p, 103 
TRF t, 103 
TRT, 105, 117 
TRT p, 103 
TRT t, 103 


Debugging Subroutines 
@AD, 117 
@CH , 117, 

@HX, 117 
@IN, 117 
@N, 121 
@NB, 117 

DEBUGP, 117, 120 
DEBUGT, 117 
decimal constant, 6 
decrement instructions, 29 
default condition 
LINK-80, 216, 218 
RMAC, 211 

default filename, 180 
default filetype, 180 
default list device, 213 
default stack, 56 
default starting address, 13 
Delimiters, 45, 74, 75 
DIF opcode, 119 
DIGIT, 196 

DIRECT macro, 163, 166, 181 
DIRECT statement, 188 
Directives; see Statements, 13 
directory search, 188 
dollar sign 

embedded, 3, 6 
in operand field, 7 
double apostrophes, 65, 74 
double semicolon, 40 
double-precision 

add instruction, 34 
storage words, 20 
DOWHILE macro, 149 
DOWHILE statement, 150 
DOWHILE-ENDDO group, 147 
drive specifications 
LINK-80, 219 
DS statement, 20 
Dummy parameters, 5, 74 
unevaluated, 78 
DUP opcode, 100, 120 
DW statement, 20, 22 

E 

ED, 3, 81 
ELSE, 44 

ELSE statement, 15 
embedded dollar sign, 3, 6 


258 




embedded macros, 66 
embedded question mark, 166 
Empty parameters, 63 

default conditions, 180 
testing, 63 

END statement, 4, 13, 14, 22 
end-of-file character, 187 
ENDDO macro, 149 
ENDIF, 44 

ENDM statement, 52 
ENDMERGE label, 197 
ENDPR label, 187 
ENDSEL, 152, 153 
ENDW macro, 142, 143 
ENTCCP macro, 35, 40 
EQU statement, 13, 14 
equivalent expressions, 10, 11 
ERASE macro, 163, 166, 181 
Error conditions 
terminal, 242 
Errors 

overflow, 54 
sequence, 196 
undefined operand, 120 
value, 9 

Escape characters, 78 
up arrow, 75 

Escape sequences, 50, 78 
evaluation 

macro parameters, 76, 77 
exclamation point 

character, 3, 7, 22 
EXITM statement, 52 
expanded macros, 66 
Expressions, 10 
bracketed, 78 
RMAC, 209 

unparenthesized, 10 
well-formed, 10, 11 

F 

false branch option, 136 
false condition, 16 
file access macros, 163 
File Control Block, 35, 179, 
180, 182 
file format 
IRL, 224 
FILE macro, 180 
FILE statement, 166 


FILERR label, 170 
FILLCB macro, 180 
FILLDEF macro, 180, 182 
FILLNAM macro, 179 
FILLNXT macro, 180 
FINIS macro, 163, 181 
FINIS statement, 166 
Flags 

condition, 25 
debug, 89 

load overlays, 230 
G 

GENCASE, 156 
GENDJMP, 149 
GENDLAB, 149 
GENDTST, 149 
GENLAB macro, 142 
GENWTST macro, 142 
GEQ macro, 119 
GET device names 
fileid, 165 
KEY, 165 

RDR (reader), 165 
GET macro, 163, 165, 182 
GET statements 
GET KEY, 165 
GET RDR, 165 
go switch, 217 


H 

hexadecimal constant, 6 
HL register pair, 34, 120 

I 

Identifiers, 3, 5, 45, 54 

controlling; see Controlling 
identifiers 
IF, 15, 44 

immediate operand instructions, 28 

increment instructions, 29 

infinite substitution, 48 

inline machine code, 100 

inline macros, 43 

inline subroutines, 207 

input and output instructions, 30 
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Instructions 

accumulator immediate, 28 
accumulator/carry, 32 
accumulator/register, 32 
call, 25 
control, 34 
CPI, 7 

data movement, 29 
DB, 7 

decrement, 29 
double-precision add, 34 
increment, 29 
input and output, 30 
jump, 25 

load and store direct, 30 
load extended immediate, 28 
LXI, 7 

move immediate, 28 
RDM, 100 
restart, 25 
return, 25 

stack pop and push, 30 
WRM, 104 
IRL file, 215 
format, 224 
IRP-ENDM group, 48 
IRPC-ENDM group, 45 
iterative improvement, 203 

J 

jump instruction, 25 

L 

label field, 3 
label generators 
GENCASE, 153 
GENDJMP, 149 
GENDLAB, 149 
GENDTST, 149 
GENELT, 153 
GENSLAB, 153 
GENSLXI, 153 
Labels, 5 

BUFFERS, 170 
constant, 44 
ENDMERGE, 197 
ENDPR, 187 
FILERR, 170 
MASLOW, 197 


optional, 20 
SAME, 196 
START, 196 
unique, 40, 45 
with leading ??, 54 
leading characters 
??, 54 

angle brackets, 74, 75 
apostrophe, 74 
asterisk, 4 
blanks, 75 

double apostrophe, 74 
percent, 75 
semicolon, 4 
string quotes, 74 
tabs, 75 
x, 75 

LIB-80 switches, 238 

line#, 3 

LINK-80 

default condition, 216 
multiline commands, 216 
run-time parameters, 216 
LINK-80 switches, 219, 216 
to 221 

additional memory, 217 
data origin, 217 
go, 217 

load address, 217 
memory size, 218 
no list, 218 

no recording of symbols, 218 
output COM file, 218 
output PRL file, 218 
program origin, 219 
? symbol, 219 
search, 219 
$, 219, 220 
listing device, 66 
LIT opcode, 118 
literal values, 1 
load address switch, 217 
load address 
LINK-80, 219 
load and store direct 
instruction, 30 
load extended immediate 
instruction, 28 
load flag 

overlays, 230 
local stack, 36 
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LOCAL statement, 40, 54 
logical operators, 8 
lower-case names, 6 
LSR macro, 119 
LSR opcode, 100 
LXI instruction, 7 

M 

machine emulation, 129 
MACLIB statement, 81 
macro calls 
multiple, 40 
Macro debugging; see 
Debugging, 89 
macro definitions, 66 
nested, 65 

macro error messages, 241 
Macro groups 

DOWHILE-ENDDO, 147 
IRP-ENDM , 48 
IRPC-ENDM, 45 
MACRO-ENDM, 57 
nested WHEN-ENDW, 141 
REPT group, 44 
REPT-ENDM, 43 
SELECT-ENDSEL, 151 
WHEN-ENDW, 141 
macro invocation, 71 
macro libraries 
COMPARE, 134 
comprehensive, 170 
DOWHILE statement, 148 
expanded NCOMPARE, 136 
NCOMPARE, 136, 139 
SELECT statement, 154 
SEQIO, 170, 171, 197 
stack machine, 108 
WHEN, 142 

WHEN statement, 144 
Zilog Z80, 81 
Macro opcodes 

machine emulation, 129 
macro redefinition, 69 
macro storage, 205 
macro subroutines, 69 
MACRO-ENDM group, 57 
Macros 
?TR, 119 
ADR, 118, 119 
BRN, 120 


CLEAR, 118 
DCL, 118 
debugging, 119 
DIRECT, 166, 181 
DOWHILE, 149 
embedded, 66 
ENDDO, 149 
ENDW, 142, 143 
ENTCCP, 35, 40 
ERASE, 166, 181 
expansion, 66 
FILE, 180 
FILLCB, 180 
FILLDEF, 180, 182 
FILLNAM, 179 
FILLNXT, 180 
GENLAB, 142 
GENWTST, 142 
GEQ, 119 
GET, 182 
inline, 43 
LSR, 119 
MOVE, 69 
negated, 136 
NEQ, 134 
NULMAC, 63 
OUTPUT, 66 
predefined, 83 
PRINT, 61 
PUT, 165, 182 
RDM, 120 
READ, 129 
RENAME, 167 
REST, 118, 119, 121 
RESTORE, 61 
RWTRACE, 120 
SAVE, 58 
SAVE, 118, 120 
SELECT, 153 
SETIO, 66 
SIZ, 118, 120 
TEST?, 130, 134 
TIMER, 87 
TYPEOUT, 40 
VAL, 119 
WCHAR, 71 
WHEN, 142, 143 
WRITE, 129 
XIT, 120 

Macros? also see file 
access macros 
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MASLOW label, 197 
master back-up, 191, 197 
master record, 191 
master sequence number, 197 
memory map, 215 
memory size switch, 218 
MERGE program, 182, 191, 196 
move immediate instruction, 28 
MOVE macro, 69 
multiline commands 
LINK-80, 216 

multiple macro calls, 40 

N 

name field 

optional, 222 
names 

overlay, 231 
NCOMPARE library, 136 
negated macro, 136 
negative values, 9 
NEQ macro, 134 

nested macro definitions, 65, 66 
nested macro groups 

see Macro groups, nested, 141 
nested overlays, 232 
nesting level restriction, 19 
NEXTSEL, 152 
no list switch, 218 
no recording symbols switch, 218 
nonmacro labels, 5 
nonzero flag, 181 
nonzero value, 17 
notation 

bracketed, 78 
NUL operator, 9, 63, 65 
null parameters, 63 
null string, 49 
NULMAC macro, 63 
numeric constants, 5, 6 

O 

octal constant, 6 
one-character strings, 7 
opcode emulation, 96 
Opcodes 

Debugging; see Debugging 
opcodes 
DIF, 119 


DUP, 100, 120 
LIT, 118 
LSR, 100 
PRN, 126 
SUM, 119 
TRT T, 122 
WRM, 100, 121 
operand field, 8 
Operand 

undefined error, 120 
undefined message, 120 
operation codes, 25 
operation field, 4, 5 
Operators 

ampersand, 45, 48 
arithmetic, 8 
concatenation, 45, 75 
logical, 8 
NUL, 63, 65 
precedence, 10 
relational, 8 
optional label, 20 
optional name field, 222 
optional value field, 222 
Options 

false branch, 136 
ORG statement, 13 
output COM file switch, 218 
OUTPUT macro, 66 
output PRL file switch, 218 
overflow error, 54 
overlapping overlays, 235 
Overlay Manager, 227 
overlays 

in command line, 231 
in PL/I programs, 228 
methods, 228, 230 
names, 231 
nested, 228, 232 
origins, 227 
overlapping, 235 
PL/I, 227 ,228 
restrictions, 228 
specification, 231 
tree structure, 227 
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p 

page 

breaks, 21 
ejects, 21 
size, 22 

PAGE statement, 21 
parameter evaluation, 77, 79 
conventions, 74 
examples, 80 

parameter specifications, 199 
Parameters 

actual; see Actual parameters 
dummy; see Dummy parameters 
empty; see Empty parameters 
run-time, 216 
percent character, 75 
percent operator, 134 
PL/I 

overlays, 228 
plus sign, 43 
predefined macros, 83 
PRINT 

macro, 61 
program, 182, 187 
subroutine, 55 
PRN 

macro, 117 
opcodes, 126 

program control structures, 

129, 142 

program origin switch, 219 
program starting address, 

13, 14 

Prototype statements, 57, 58, 

61, 66 

plus sign, 59 
recursive macros, 71 
redefining, 69 
Pseudo operations, 13, 22 
DB, 13 
DS, 13 
DW, 13 

ELSE, 13, 44 
END, 13 
ENDIF, 13 
EQU, 13 
EXITM, 52 
IF, 13, 44 
IRP, 35 
IRPC, 35 


ORG, 13 
PAGE, 13 
REPT, 35, 43 
SET, 13 
TITLE, 13 
PUT 

device names, 165 
macro, 163, 165, 182 


PUT statements 


PUT 

CON, 

165 


PUT 

LST, 

165, 

166 

PUT 

PUN, 

165 


PUT 

ZAP, 

165, 

166 


Q 


question mark 
embedded, 166 
quoted strings, 65, 78 

R 

radix indicators, 5, 6 
Random Access Memory, 89 
RDM instruction, 100 
RDM macro, 120 
READ macro, 129 
READM, 196 
READU, 196 
records 

updated, 191 
recursion, 71 
recursive macros 
invocation, 71 
prototype statements, 71 
redefinition 
of macros, 69 
register-to-register move 
instructions, 29 
registers 

restoring, 61 
REL file, 237 
relational operators, 8 
relocatable object code 
LINK-80, 225 

relocatable object file, 209 
relocatable object module, 
215, 222 

RENAME macro, 163, 167, 181 
REPT group, 44 
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REPT loop, 100 
REPT-ENDM group, 43 
reserved symbols, 205 
reserved words, 6, 13 
REST macro, 118, 119, 121 
restart instruction, 25 
RESTORE macro, 61 
restrictions 

overlays, 227, 228 
return instruction, 25 
RMAC 

default condition, 211 
expressions, 209 
run-time error messages 
LINK-8, 251 

run-time parameters, 216 
RWTRACE macro, 120 

S 

SAME label, 196 
SAVE macro, 58, 118, 120 
search switch, 219 
SELECT group 
CASE@m, 152 
ENDSEL, 152 
NEXTSEL, 152 
SELVn , 152 
SELECT macro, 153 
SELECT-ENDSEL group, 151 
select-vector, 152 
SELNEXT, 153, 156 
SELVn, 152 
semicolon 
double, 40 
leading, 4 
SEQERR, 196 
SEQIO library, 197 
sequence errors, 196 
SET statement, 15, 170 
SETIO macro, 66 
SID, 215 

single-character commands, 

160, 163 

single-character escape, 75 
single-character flags, 241 
single-precision storage, 19 
SIZ macro, 118, 120 
source program line number , 3 
special characters 
LINK-80, 220 


special link items, 222 
stack machine macro library, 108 
stack pointer, 36 
stack pop and push 
instructions, 30 
START label, 40, 196 
statement elements 
comment, 3 
label, 3 
line#, 3 
operand, 3 
operation, 3 
Statements 
ASEG, 210 
COMMON, 211 
CSEG, 211 
DB, 22 
DIRECT, 188 
DS, 20 
DSEG, 211 
DW, 20, 22 
ELSE, 15 
END, 13, 14 
ENDM, 52 
EQU, 13, 14 
EXITM, 52 
EXTRN, 212 
FILE, 166, 181 
FINIS, 166 
IF, 15 

LOCAL, 40, 54 
MACLIB, 81 
NAME, 212 
ORG, 13 

prototype; see Prototype 
statements 
PAGE, 21 
PUBLIC, 211 
PUT, 166 
SET, 15, 170 
TITLE, 21 
storage words 

double-precision, 20 
storage 

in symbol table, 206 
macro, 205 
single-precision, 19 
symbol table, 205 
string characters, 20 
string constants, 7, 21 
string quotes, 45, 74, 78 
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subexpressions, 10 
Subroutines 
inline, 207 
PRINT, 55 

Subroutines; also see 
Utility Subroutines 
Substitution 

dummy parameters, 74, 75 
infinite, 75 
rules, 50 
SUM opcode, 119 
Switches 

LIB-80, 238 

LINK-80? see LINK-80 switches 
SYM file, 188 
symbol storage 

requirements, 205 
symbol table, 40 

overflow message, 206 
storage, 205, 217 
temporary storage, 206 
symbols 

base page, 221 
defined in equates, 221 
relocatable in base page, 221 
undefined, 232 
user-defined, 219 

T 

tab characters, 1, 3 
leading, 75 

terminal error conditions, 242 
TEST? macro, 130, 134 
TIMER macro, 87 
TITLE statement, 21 
tree structured overlays, 227 
TRT T opcode, 122 
two-character strings, 7 
TYPE command, 196 
TYPEOUT macro, 40 

U 

UGEN macro, 117 

undefined operand error, 120 


undefined operand message, 120 
undefined symbols, 232 
unique label, 40, 45 
up arrow 

as escape character, 75 
update back-up, 191 
update records, 191 
upper-case names, 6 
use factor, 215 
user-defined symbols, 219 
utility subroutines, 40, 196 

V 

VAL macro, 119 
value errors, 9 
value field 
optional, 222 
values 

negative, 9 

W 

WCHAR macro, 71 
well-formed expressions, 11 
WHEN macro, 142, 143 
WHEN macro library, 142 
WHEN-ENDW group, 141 
WRITE macro, 129 
WRITE statement, 151 
WRITESEQ, 196 
WRM instruction, 104 
WRM opcode, 100, 121 

X 

XIT macro, 120 
XREF, 213 

Z 

zero value, 17 
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Reader Comment Form 

We welcome your comments and suggestions. They help us provide you with better 
product documentation. 

Date _Manual Title _Edition- 

1. What sections of this manual are especially helpful? 


2. What suggestions do you have for improving this manual? What information 
is missing or incomplete? Where are examples needed? 


3. Did you find errors in this manual? (Specify section and page number.) 


COMMENTS AND SUGGESTIONS BECOME THE PROPERTY OF DIGITAL RESEARCH. 
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Programmer's Utilities Guide 
for the CP/M® Family of Operating Systems 

Release Notes 

Addendum to the First Printing—1982 


Copyright© 1982 by Digital Research 
CP/M is a registered trademark of Digital Research. 
LINK-80 and MP/M are trademarks of Digital Research. 
Compiled December 1982 


The following LINK-80™ option switches are not documented in 
Section 15.4 of The Programmer's Utilities Guide for the CP/M ® 
Family of Operating Systems. 


The BIOS Link (B) Switch 

The B switch is used to link a BIOS in a banked CP/M 3 system. 
LINK-80 aligns the data segment on a page boundary, puts the length 
of the code segment in the header, and defaults to the SPR filetype. 


The Output RSP File (OR) Switch 

The OR switch outputs RSP (Resident System Process) files for 
execution under MP/M™ . 


The Output SPR File (OS) Switch 

The OS switch outputs SPR (System Page Relocatable) files for 
excution under MP/M. 


All Information Presented Here is Proprietary to Digital Research 
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CP/M Plus (CP/M® Version 3) Operating System System Guide 

Release Notes 

Copyright © 1983 by Digital Research 
CP/M is a registered trademark of Digital Research. 

CP/M Plus is a trademark of Digital Research. 
Compiled February 1983 


( np/ M ® T !l* ^ f i °^ lo , v I 1 " g pag ® s present corrections to the CP/M Plus" 
1 £°/ M —Version 3 ) Operating System System Guide . —- 

PAGES 50 AMD 161 

Function number 22 in Table 3-10 (paqe 50) and Tahlo r-i 
parameter:* S incorrect * In Funct ion 22, DRVTBL, delete this output 



HL 

II 

O 

a 

a 



PAGE 

120 




On page 120, lines 243, 
Replace them with the following 

256, 291, and 302 
code: 


243 

OOE9 0600 

■vi b,0 

J start with device 0 


256 

00PP 04 

inr b 

l next device number 


291 

0115 0600 

■vi b,o 

i start with device 0 


302 

0123 04 

inr b 

i next device number 

PAGE 

121 




with 

On page 121, lines 
the following code: 

371 and 

377 are incorrect. 


371 

0180 0600 

mvi b ,0 

1 start with device 0 


J77 

018A 04 

inr b 

f next Jev ice number 

PAGE 

122 




with 

On page 122, lines 
the following code: 

402 and 

409 are incorrect. 


402 

019C 0600 

mvi b,0 



4 09 

01A8 04 

inc b 

i else, next device 


them 
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CP/M Plus System Guide 


Release Notes 


PAGE 137 

On page 137, lines 27, 28, 29, and 59 are incorrect. Replace 
them with the following code: 

27 0000 2100802200 1*1 h,08000h I shld @clvec I shld Ocovec I assign console to CRT: 

28 0009 2100402200 lxl h,64000h I slylf?. glovec » assign printer to LPT: 

29 000r 2100202200 * lxl h,0200Qh I shld faivec I shld Oaovec i aanign AUX CRT1: 


59 0026 2100010180 


lxl h,OlOOh I lxl b,0C80h 


{ clone 3.125K, just in csss 


PAGE 138 * 

On page 138, line 79 is incorrect. Replace with the 
following code: 

79 0056 2100010180 lxl h,OlOOh I lxl b,0C80h : clone 3.125K 


PAGE 9 


*•) ■ 

O v 


'.t 


Figure 1-6, Memory Organization! in Nonbanked CP/M 3, is 
incorrect. The following Fijgate 1-6 is corrects " 


Buffers and Hash Tables 


BIOS 


BOOS 


PROGRAM LOADER 


Qptlop^l.o^rl^S 


TRANSIENT PROGRAM 


"! BASE PAGE Oh - 


t* 


Figure 1-6. Memory Organization in Nonbanked CP/M 3 
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